Variantes na Koder Stack

1. Definição

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

1. *urface*— qual superfície de interação ela expõe (mobile, desktop,

   tv, web, cli, tui, engine, backend).

2. *arget*— qual plataforma/SO ela executa (linux, macos, windows,

   android, ios, tizenos, webos, browser, universal).

3. *orm 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 *oda* 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)

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).

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)

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 *or 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. *empre dizer "variante" em vez de "versão" ao se referir a uma

   combinação de surfacetargetform* "Versão" fica reservado para release temporal.

2. *aming consistente* <sector>-<surface> ou

   <sector>-<surface>-<target> — nunca inventar variações ad-hoc.

3. *ada 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. *aridade é entre variantes, não entre "UIs" ou "plataformas"*—

   o termo unifica os três eixos.

5. *rand 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.