fix: make OCR portable and reliable across AMD64 and ARM64 (#519)

* fix: make OCR portable and reliable

* fix: harden OCR installation portability

* fix: pin OCR partials across downloads

* fix: make OCR execution reliably asynchronous

* fix: harden OCR portability and docs routes

* fix: preserve decoder and docs safeguards

apps/docs/pt-BR/api/ai.md

@@ -1,18 +1,26 @@
 ---
 description: "Referência do motor de IA com todas as ferramentas de ML locais. Remoção de fundo, ampliação, OCR, detecção de rostos, restauração de fotos e muito mais."
-i18n_source_hash: 14728c1dcd05
-i18n_provenance: machine
-i18n_output_hash: 9c63b9ba2ca7
+i18n_output_hash: 37b479358342
+i18n_source_hash: aa9a56cdddc7
+i18n_provenance: human
 ---
 
 # Referência do Motor de IA {#ai-engine-reference}
 
-O pacote `@snapotter/ai` conecta o Node.js a um **sidecar Python persistente** para todas as operações de ML. O processo despachante permanece ativo entre as requisições para um desempenho rápido com início a quente. O NVIDIA CUDA é detectado automaticamente na inicialização e usado quando disponível; caso contrário, as ferramentas de IA rodam na CPU.
+O pacote `@snapotter/ai` coordena ferramentas nativas e tempos de execução Python para operações ML locais. A maioria das ferramentas ML usa um Python sidecar persistente para inicializações a quente rápidas. OCR é intencionalmente separado: `fast` invoca o binário Tesseract nativo, enquanto `balanced` e `best` usam um JSONL dispatcher persistente dedicado fixado na geração RapidOCR ativa e imutável em `/data/ai/v3`. Cada solicitação contém um generation lease. Durante uma atualização, SnapOtter executa um smoke test no candidato antes da ativação, alterna atomicamente para o novo dispatcher e, em seguida, drena a geração antiga antes de garbage collection.
+
+NVIDIA CUDA é detectado automaticamente e usado por tempos de execução que o suportam. OCR usa CPU em todos os hosts, incluindo sistemas com GPUs NVIDIA, evitando CUDA e acoplamento de driver para esta ferramenta.
 
 A aceleração por iGPU Intel/AMD via VA-API, Quick Sync ou OpenCL não é suportada para inferência de IA hoje. Mapear `/dev/dri` em um contêiner não acelera essas ferramentas do sidecar Python a menos que uma GPU NVIDIA compatível com CUDA esteja disponível.
 
 19 ferramentas de IA no sidecar Python em quatro modalidades (imagem, áudio, vídeo, documento), mais 2 ferramentas com capacidades opcionais de IA. Todos os modelos rodam localmente - nenhuma conexão com a internet é necessária após o download inicial do modelo.
 
+
+<!-- korean-ocr-contract:start -->
+::: info Compatibilidade do OCR em coreano
+O OCR rápido oferece suporte a `auto`, `en`, `de`, `es`, `fr`, `zh` e `ja`, mas não a coreano (`ko`). Coreano exige o pacote de OCR preciso e `balanced` ou `best`. O pacote funciona nos contêineres oficiais Linux amd64 e arm64, inclusive em hosts NVIDIA, onde o OCR continua na CPU. Sistemas não compatíveis recebem um erro explícito e nunca retornam silenciosamente para `fast`. Coreano com `fast` ou com o alias legado `tesseract` é rejeitado antes da fila com `FEATURE_INCOMPATIBLE` e `fast-korean-unsupported`.
+:::
+<!-- korean-ocr-contract:end -->
 ## Arquitetura {#architecture}
 
 ```
@@ -22,15 +30,17 @@ Node.js Tool Route
  @snapotter/ai bridge.ts
       | (stdin/stdout JSON + stderr progress events)
       v
- Python dispatcher (persistent process, "ai" profile)
+ +-- Native Tesseract + Ghostscript (fast image/PDF OCR)
+ |
+ +-- Isolated OCR runtime (persistent JSONL dispatcher)
+ |     `-- RapidOCR + ONNX Runtime CPU + pinned PP-OCR models
+ |
+ `-- Python dispatcher (persistent process, "ai" profile)
       |
       |-- remove_bg.py        (rembg / BiRefNet)
       |-- upscale.py          (RealESRGAN)
       |-- inpaint.py          (LaMa ONNX)
       |-- outpaint.py         (LaMa canvas expansion)
-      |-- ocr.py              (PaddleOCR / Tesseract)
-      |-- ocr_pdf.py          (page-by-page document OCR)
-      |-- ocr_preprocess.py   (image enhancement for OCR)
       |-- detect_faces.py     (MediaPipe)
       |-- face_landmarks.py   (MediaPipe landmarks)
       |-- enhance_faces.py    (GFPGAN / CodeFormer)
@@ -52,7 +62,7 @@ Os modelos de IA são empacotados por pilha de dependências compartilhada, e n
 
 A imagem Docker inclui a aplicação mais o runtime comum. Arquivos grandes de modelos são baixados sob demanda para o volume persistente `/data/ai`, e depois reutilizados por todas as ferramentas que precisam deles. Se um pacote já estiver instalado porque outra ferramenta precisou dele, habilitar uma nova ferramenta dependente não baixa esse pacote novamente.
 
-Cada ferramenta de IA requer um ou mais pacotes de recursos antes de poder rodar. A interface de administração instala por ferramenta através de `POST /api/v1/admin/tools/:toolId/features/install`, que resolve a lista completa de pacotes, pula os pacotes já instalados e enfileira apenas os downloads que faltam. Por exemplo, habilitar Foto para Passaporte em uma instância nova enfileira `background-removal` e `face-detection`; habilitá-la depois que a Remoção de Fundo já estiver instalada enfileira apenas `face-detection`.
+A maioria das ferramentas de IA requer um ou mais pacotes de recursos antes de serem executadas. A UI administrativa os instala por ferramenta por meio do `POST /api/v1/admin/tools/:toolId/features/install`, que resolve a lista completa de pacotes, ignora os pacotes que já estão instalados e enfileira apenas os downloads ausentes. Por exemplo, ativar a foto do passaporte em uma nova instância enfileira `background-removal` e `face-detection`; habilitá-lo após a remoção de segundo plano já estar instalada enfileira apenas `face-detection`. OCR é a exceção porque `fast` não precisa de pacote; instale seu tempo de execução preciso opcional por meio da UI ou `POST /api/v1/admin/features/ocr/install`.
 
 | Pacote | Tamanho | Grupo de dependências compartilhado | Ferramentas que o usam |
 |--------|------|-------------------------|-------------------|
@@ -61,7 +71,7 @@ Cada ferramenta de IA requer um ou mais pacotes de recursos antes de poder rodar
 | `object-eraser-colorize` | 1-2 GB | inpainting/outpainting LaMa e DDColor | erase-object, colorize, ai-canvas-expand |
 | `upscale-enhance` | 5-6 GB | RealESRGAN, GFPGAN / CodeFormer, remoção de ruído | upscale, enhance-faces, noise-removal |
 | `photo-restoration` | 4-5 GB | reparo de arranhões e pipeline de restauração | restore-photo |
-| `ocr` | 5-6 GB | pilha de OCR PaddleOCR / Tesseract | ocr, ocr-pdf |
+| `ocr` | ~208-234 MiB baixado / ~409-488 MiB instalado | Modelos opcionais RapidOCR 3.9.1, ONNX Runtime 1.20.1 e PP-OCR fixado | ocr, ocr-pdf (somente `balanced` e `best`) |
 | `transcription` | ~600 MB | modelos de fala para texto faster-whisper | transcribe-audio, auto-subtitles |
 
 Ferramentas com dependências entre pacotes:
@@ -71,7 +81,17 @@ Ferramentas com dependências entre pacotes:
 | `passport-photo` | `background-removal`, `face-detection` | Remove o fundo e depois usa marcos faciais para enquadrar o recorte conforme as regras de fotos de passaporte e documentos de identidade. |
 | `enhance-faces` | `upscale-enhance`, `face-detection` | Detecta rostos antes de rodar o realce GFPGAN ou CodeFormer nas regiões de rosto selecionadas. |
 
-Uma ferramenta fica disponível apenas quando todos os seus pacotes necessários estão instalados. Instalações parciais são válidas e tratadas de forma incremental: pacotes instalados são reutilizados, pacotes que faltam são mostrados como downloads e as instalações enfileiradas rodam uma de cada vez para que o ambiente Python compartilhado não seja modificado simultaneamente.
+Uma ferramenta está disponível somente quando todos os seus pacotes necessários estão instalados, exceto OCR: sua camada `fast` integrada permanece disponível sem o pacote OCR opcional. As instalações parciais são válidas e tratadas de forma incremental: os pacotes configuráveis ​​instalados são reutilizados, os pacotes perdidos são mostrados como downloads e as instalações na fila são executadas uma de cada vez, para que o ambiente Python compartilhado não seja modificado simultaneamente.
+
+### Instalação precisa do tempo de execução do OCR {#accurate-ocr-runtime-installation}
+
+O pacote OCR preciso é um tempo de execução específico da plataforma para o contêiner oficial Linux amd64 ou Linux arm64. A construção amd64 usa Python 3.12; a compilação arm64 usa Python 3.11. Ambas as compilações executam RapidOCR por meio do `CPUExecutionProvider` do ONNX Runtime, portanto, o mesmo pacote funciona apenas em hosts CPU e NVIDIA Docker. O tempo de execução preciso requer pelo menos 4 GiB de memória efetiva: o limite cgroup do contêiner configurado, caso contrário, memória do host. Um sistema abaixo do mínimo de compatibilidade assinado é rejeitado antes do download. Este requisito não se aplica ao Fast OCR integrado. As compilações Bare-metal são rejeitadas porque seus libc e Python ABI não podem ser inferidos com segurança; O OCR rápido permanece disponível quando o host fornece Tesseract e Ghostscript.
+
+O artefato opcional tem cerca de 208-234 MiB compactado e 409-488 MiB extraído, dependendo da arquitetura. O índice assinado vincula as contagens exatas de bytes compactados e extraídos impostas pelo instalador. Tesseract integrado adiciona cerca de 25 MiB à imagem oficial e não precisa de arquivos em `/data/ai`.
+
+A instalação online busca um índice de versão assinado e o artefato exato endereçado ao conteúdo para a plataforma atual. SnapOtter verifica a assinatura do índice Ed25519, tamanho do artefato, resumo SHA-256, resumos de modelo, caminhos, modos de arquivo e smoke test preparado antes de ativar atomicamente a nova geração. Uma instalação com falha deixa a geração íntegra anterior ativa.
+
+Para instalação isolada, carregue o `ocr-runtime-index.json` da versão e o arquivo de tempo de execução OCR correspondente para `POST /api/v1/admin/features/import` usando campos multipartes chamados `index` e `archive`. A importação offline aplica as mesmas verificações de assinatura, hash, extração, compatibilidade e teste de fumaça da instalação online; um arquivo sem seu índice assinado confiável é rejeitado.
 
 ---
 
@@ -143,16 +163,16 @@ Desfoca o fundo mantendo o sujeito nítido.
 ## OCR / Extração de Texto {#ocr-text-extraction}
 
 **Rota da ferramenta:** `ocr`  
-**Modelos:** Tesseract (rápido), PaddleOCR PP-OCRv5 (equilibrado), PaddleOCR-VL 1.5 (melhor)
+**Modelos:** Tesseract (`fast`); RapidOCR com modelos pequenos PP-OCRv6 (`balanced`); Modelos médios PP-OCRv6 com pontuação de variante calibrada (`best`)
 
 | Parâmetro | Tipo | Padrão | Descrição |
 |-----------|------|---------|-------------|
-| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | Nível de processamento |
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dinâmico | Quando `quality` e `engine` são omitidos, o SnapOtter escolhe o melhor nível disponível nesta ordem: `best`, `balanced`, `fast`. Para coreano, `fast` nunca é escolhido; usa-se `best`, depois `balanced`, ou é retornado o erro de instalação ou compatibilidade do runtime preciso. |
 | `language` | string | `"auto"` | Idioma: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
-| `enhance` | boolean | `true` | Pré-processar a imagem para melhorar a precisão do OCR |
-| `engine` | string | - | Obsoleto. Mapeia `tesseract` para `fast`, `paddleocr` para `balanced` |
+| `enhance` | booleano | Dependente do nível | Melhore o contraste local. Fast aplica-o diretamente; níveis precisos mantêm a variante somente quando a pontuação calibrada melhora OCR. O padrão é Melhor |
+| `engine` | corda | - | Alias ​​de compatibilidade obsoleta. Mapeia `tesseract` para `fast` e o valor herdado de `paddleocr` para `balanced`; não carrega PaddlePaddle |
 
-Retorna resultados estruturados com caixas delimitadoras, pontuações de confiança e blocos de texto extraídos.
+Retorna o texto extraído mais os metadados de origem: mecanismo, qualidade solicitada e real, dispositivo, provedor, estado de degradação, avisos e versões de tempo de execução/modelo precisos, quando aplicável. Solicitações de qualidade explícitas nunca voltam para outro nível. Se `balanced` ou `best` não estiver disponível, API retornará `FEATURE_NOT_INSTALLED` ou `FEATURE_INCOMPATIBLE` em vez de executar `fast` silenciosamente.
 
 ## OCR de PDF {#pdf-ocr}
 
@@ -163,9 +183,13 @@ Extrai texto de documentos PDF digitalizados usando OCR com IA, página por pág
 
 | Parâmetro | Tipo | Padrão | Descrição |
 |-----------|------|---------|-------------|
-| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | Nível de processamento |
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dinâmico | Quando `quality` e `engine` são omitidos, o SnapOtter escolhe o melhor nível disponível nesta ordem: `best`, `balanced`, `fast`. Para coreano, `fast` nunca é escolhido; usa-se `best`, depois `balanced`, ou é retornado o erro de instalação ou compatibilidade do runtime preciso. |
 | `language` | string | `"auto"` | Idioma: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
 | `pages` | string | `"all"` | Seleção de páginas: `"all"`, `"1-3"`, `"1,3,5"` |
+| `enhance` | booleano | Dependente do nível | Melhore o contraste local. Fast aplica-o diretamente; níveis precisos mantêm a variante somente quando a pontuação calibrada melhora OCR. O padrão é Melhor |
+| `engine` | corda | - | Alias ​​de compatibilidade obsoleta. Mapeia `tesseract` para `fast` e o valor herdado de `paddleocr` para `balanced`; não carrega PaddlePaddle |
+
+A mesma regra de não downgrade se aplica a PDF OCR. As páginas PDF são rasterizadas antes do reconhecimento e uma solicitação pode selecionar no máximo 50 páginas.
 
 ## Desfoque de Rosto / PII {#face-pii-blur}