ForgeLM/.planning/quick/2-preflight-llama-native-deps-startup/2-PLAN.md

---
phase: quick
plan: 2
type: execute
wave: 1
depends_on: []
files_modified:
  - tauri-app/src-tauri/src/runtime/mod.rs
  - tauri-app/src-tauri/src/runtime/process.rs
  - tauri-app/src-tauri/src/runtime/state.rs
  - crates/inference-core/src/engine.rs
  - crates/llama-sys/src/lib.rs
autonomous: true
requirements: []
must_haves:
  truths:
    - "O desktop detecta antes do start se as dependencias nativas do llama estao ausentes ou inacessiveis"
    - "Quando possivel, o app baixa/prepara automaticamente os artefatos nativos requeridos antes de iniciar o backend local"
    - "Falhas de preflight aparecem no RuntimeSnapshot com mensagem acionavel, sem spawn parcial do backend"
  artifacts:
    - path: "tauri-app/src-tauri/src/runtime/mod.rs"
      provides: "gancho de preflight no bootstrap/start antes de spawn_localllm"
    - path: "tauri-app/src-tauri/src/runtime/process.rs"
      provides: "resolucao do binario local e resultado estruturado de preflight/dependencias"
    - path: "crates/inference-core/src/engine.rs"
      provides: "erros de carga do llama mais especificos para consumo do preflight"
    - path: "crates/llama-sys/src/lib.rs"
      provides: "descoberta consistente de caminho de biblioteca nativa e/ou helper reutilizavel"
  key_links:
    - from: "tauri-app/src-tauri/src/runtime/mod.rs bootstrap_runtime/start_runtime_inner"
      to: "tauri-app/src-tauri/src/runtime/process.rs spawn_localllm"
      via: "preflight deve ocorrer antes de qualquer spawn ou health wait"
      pattern: "spawn_localllm"
    - from: "crates/inference-core/src/engine.rs InferenceEngine::load"
      to: "crates/llama-sys/src/lib.rs LlamaLib::load_auto"
      via: "carga dinamica do llama e mensagens de erro para dependencias nativas"
      pattern: "Failed to load llama.dll"
---

<objective>
Adicionar um preflight no startup do desktop/backend para verificar se o runtime local tem as dependencias nativas do llama disponiveis e, quando houver origem configurada/suportada, baixar ou preparar esses artefatos antes de iniciar o backend.

Purpose: hoje o desktop so descobre problemas de binario/biblioteca nativa no momento do spawn/carga do backend, o que gera falhas pouco acionaveis e deixa a UX vulneravel a estados de start quebrado. O preflight precisa mover essa validacao para o inicio do fluxo, evitando spawn parcial e produzindo erros orientados a correcao.

Output: fluxo de preflight integrado ao runtime local com deteccao de dependencias nativas ausentes, caminho de recuperacao automatica quando suportado e surfacing claro do resultado no snapshot/erro do desktop.
</objective>

<context>
@.planning/STATE.md
@tauri-app/src-tauri/src/runtime/mod.rs
@tauri-app/src-tauri/src/runtime/process.rs
@tauri-app/src-tauri/src/runtime/state.rs
@crates/inference-core/src/engine.rs
@crates/llama-sys/src/lib.rs
</context>

<tasks>

<task type="auto">
  <name>Task 1: Definir contrato de preflight e pontos de integracao no startup local</name>
  <files>
    tauri-app/src-tauri/src/runtime/mod.rs
    tauri-app/src-tauri/src/runtime/process.rs
    tauri-app/src-tauri/src/runtime/state.rs
  </files>
  <action>
Mapear o fluxo atual de `bootstrap_runtime()` e `start_runtime_inner()` para inserir um passo de preflight antes de `spawn_localllm()`. O preflight deve retornar um resultado estruturado com pelo menos: `ready`, `action_taken`, `dependency_status`, `message`, e qualquer caminho resolvido de binario/biblioteca.

Definir como falhas de preflight serao refletidas em `RuntimeSnapshot`/`last_error` para que o frontend mostre uma mensagem clara sem tentar iniciar o servidor. Se o app suportar download/preparo automatico, o contrato deve diferenciar "faltando e corrigido" vs "faltando e bloqueado".

Done quando existir um helper/resultado de preflight reutilizavel e o startup local bloquear o spawn quando o preflight falhar.
  </action>
  <verify>
    <automated>cargo check -p tauri-app</automated>
  </verify>
  <done>
    - `bootstrap_runtime` e `start_runtime_inner` executam preflight antes do spawn
    - Resultado de preflight alimenta erro acionavel no snapshot
    - Nenhum processo do backend e iniciado quando dependencias nativas faltam
  </done>
</task>

<task type="auto">
  <name>Task 2: Implementar verificacao/download das dependencias nativas do llama</name>
  <files>
    tauri-app/src-tauri/src/runtime/process.rs
    crates/inference-core/src/engine.rs
    crates/llama-sys/src/lib.rs
  </files>
  <action>
Revisar como `LlamaLib::load_auto()` localiza `llama.dll`/`libllama.*` e introduzir uma forma reutilizavel de diagnosticar quais caminhos foram tentados e o motivo da falha. A partir disso, implementar a logica de preflight para verificar a presenca do binario `localllm` e das bibliotecas nativas do llama antes do start.

Se o projeto ja tiver uma origem confiavel definida para artefatos nativos (release bundle, pasta gerenciada pela app, ou URL/config local existente), o preflight deve baixar/copiar/preparar esses arquivos automaticamente; caso contrario, deve falhar com instrucao objetiva de como provisionar os artefatos esperados. Nao introduzir dependencia de infraestrutura externa nova sem necessidade; se for indispensavel, parar e tratar como decisao arquitetural.

Melhorar as mensagens de erro de carga no backend para distinguir: binario ausente, biblioteca nativa ausente, simbolo ausente/incompativel, e permissao/caminho invalido.
  </action>
  <verify>
    <automated>cargo check -p llama-sys -p inference-core -p tauri-app</automated>
  </verify>
  <done>
    - Preflight detecta binario local e bibliotecas nativas do llama antes do start
    - Fluxo automatizado prepara/baixa dependencias quando suportado
    - Mensagens de erro diferenciam ausencia de artefato vs incompatibilidade de carga
  </done>
</task>

<task type="auto">
  <name>Task 3: Cobrir regressao de startup e bootstrap do desktop</name>
  <files>
    tauri-app/src-tauri/src/runtime/state.rs
    tauri-app/src-tauri/src/runtime/mod.rs
    tauri-app/src-tauri/src/runtime/process.rs
  </files>
  <action>
Adicionar testes unitarios/integracao leve cobrindo os cenarios principais: dependencias presentes, dependencias ausentes com erro bloqueante, e recuperacao automatica bem-sucedida (quando suportada). Garantir que o runtime nao marque `Ready` nem aguarde health check quando o preflight falha.
  </action>
  <verify>
    <automated>cargo test -p tauri-app runtime:: -- --nocapture</automated>
  </verify>
  <done>
    - Testes cobrem falha e sucesso do preflight no startup local
    - RuntimeSnapshot exposto ao frontend preserva mensagem/estado coerentes
    - Autostart no bootstrap respeita o mesmo gate de preflight do start manual
  </done>
</task>

</tasks>

<verification>
- `cargo check -p llama-sys -p inference-core -p tauri-app` passa
- `cargo test -p tauri-app runtime:: -- --nocapture` cobre gating de preflight
- Startup manual e autostart nao executam spawn quando faltam dependencias nativas do llama
- Mensagens de erro indicam acao concreta para restaurar o runtime local
</verification>

<success_criteria>
- Um operador entende antes do start se o runtime local esta pronto para carregar o llama
- O app corrige automaticamente a falta de dependencias quando existir origem suportada
- Falhas de dependencias nativas nao aparecem mais como erro generico tardio de spawn/health
</success_criteria>

<output>
Ao concluir a execucao futura, criar `.planning/quick/2-preflight-llama-native-deps-startup/2-SUMMARY.md`
</output>