Variantes na Koder Stack

1. Definição

Uma variante é uma instância executável de um componente Koder para uma combinação específica de:

1. Surface — qual superfície de interação ela expõe (mobile, desktop, tv, web, cli, tui, engine, backend).
2. Target — qual plataforma/SO ela executa (linux, macos, windows, android, ios, tizenos, webos, browser, universal).
3. Form factor — qual fator de forma de dispositivo ela serve (phone, tablet, tv, laptop, desktop, terminal, server, embedded).

Uma variante é o que o usuário final roda. Não é o código-fonte (isso é um componente L4), nem o arquivo binário entregue (isso é um artefato), nem a release temporal (isso é uma versão).

Exemplos

2. Distinção de termos relacionados

A combinação completa que identifica algo único em produção: <sector> + <variant> + <release> → ex: hub + cli-linux + v2.3.0.

3. Vocabulário fechado

3.1 — Surface (eixo de UI/forma de consumo)

Mapeia 1:1 com o L4 de RFC-006:

3.2 — Target (eixo de plataforma/SO)

Para a surface extension, o eixo "target" mapeia ao runtime de extensão / loja (chromium, gecko, safari), não ao SO — análogo a como engine usa o pseudo-target universal. Cada engine tem manifest, set de APIs, pipeline de release e loja distintos (ver rfcs/kruze-RFC-001).

A coluna Readiness registra se o target tem pipeline de release ativa hoje. Fonte de verdade canônica e mecânica de flip: registries/ target-readiness.md. Os enums acima continuam todos legais — um target inactive pode aparecer em koder.toml [app] platforms como planejamento futuro, mas qualquer CI job que tente buildá-lo deve gatear (if: false / runs-on: never / equivalente) até a registry flipar pra active.

3.3 — Form factor (eixo de dispositivo)

4. Combinações válidas

Nem todo cruzamento surface × target × form_factor faz sentido. A matriz canônica:

Combinações ausentes da matriz não devem ser inventadas sem RFC explícita (análogo ao RFC-006 §3.4 para adicionar nova surface). A surface extension foi adicionada por rfcs/kruze-RFC-001 (ratificada 2026-05-30).

5. Naming canônico

<sector>-<surface>-<target>

Exemplos:

• hub-cli-linux
• talk-mobile-android
• kmail-web-browser
• pass-desktop-macos

Para multi-target (ex: Flutter mobile que cobre Android + iOS no mesmo código), usar a surface em vez do target específico:

• talk-mobile (cobre talk-mobile-android e talk-mobile-ios)
• pass-desktop (cobre pass-desktop-linux/macos/windows)
• kruze-extension (cobre kruze-extension-chromium/gecko/safari)

Variantes com brand B2B usam o prefixo da brand:

• raven-web-browser (variante web do Raven, não do Kmail)
• nimbus-cli-linux (variante CLI do Nimbus)

6. Onde aparecem

6.1 — koder.manifest.json

O /k-manifest lista uma entrada variants[] por componente, com schema:

{
  "variants": [
    {
      "name": "hub-cli-linux",
      "surface": "cli",
      "target": "linux",
      "form_factor": "terminal",
      "source": "products/dev/hub/app/cli/",
      "artifact": "hub_x.y.z_amd64.deb"
    }
  ]
}

6.2 — /k-parity

A "matriz de paridade de UIs" é literalmente a matriz de variantes do componente: cada coluna é uma variante, cada linha é uma feature, cada célula é o estado dessa feature naquela variante.

6.3 — /k-test, /k-bench

Os testes e benchmarks rodam por variante. Um relatório de teste declara a variante alvo (talk-mobile-android é distinto de talk-mobile-ios, mesmo compartilhando 95% do código).

6.4 — Naming de pacote, container, serviço

Pacotes Linux: <sector>-<surface> (sem target, que vem da arch)

• hub-cli → hub-cli_2.3.0_amd64.deb, hub-cli_2.3.0_arm64.deb

Containers Docker: koder/<sector>-<surface>

• koder/kmail-backend:v2.3.0

Systemd services: koder-<sector>-<surface>.service

• koder-hub-backend.service

7. Regras de uso (normativo)

1. Sempre dizer "variante" em vez de "versão" ao se referir a uma combinação de surface/target/form. "Versão" fica reservado para release temporal.
2. Naming consistente: <sector>-<surface> ou <sector>-<surface>-<target> — nunca inventar variações ad-hoc.
3. Cada variante tem manifest próprio: declarações de capabilities, permissions, dependencies por variante (uma variante CLI não pede permissão de microfone; uma variante mobile pede).
4. Paridade é entre variantes, não entre "UIs" ou "plataformas" — o termo unifica os três eixos.
5. Brand variants (par engine+product) seguem a mesma regra: raven-backend-linux e kmail-backend-linux são variantes distintas, mesmo que partilhem código.

8. Anti-padrões

• ❌ "Versão Linux do Hub" → ✅ "Variante CLI Linux do Hub"
• ❌ "Plataforma Android do Talk" → ✅ "Variante mobile Android do Talk"
• ❌ "Build do Pass para iPad" → ✅ "Variante mobile iOS form factor tablet do Pass"
• ❌ Naming hub-linux-cli (ordem errada) → ✅ hub-cli-linux
• ❌ Inventar surface fora do vocabulário fechado (ex: hub-watch-watchos) sem RFC

9. Migração

Documentos pré-existentes que usam "versão de UI", "versão de plataforma", "build para X" devem ser progressivamente atualizados para "variante", sem quebrar refs antigas. O /k-housekeep audita e abre tickets para correções.