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

Componente	Variante	Naming canônico
Koder Hub	App mobile Android em celular	hub-mobile-android
Koder Hub	App desktop Linux em laptop	hub-desktop-linux
Koder Hub	CLI Linux em terminal	hub-cli-linux
Koder Hub	Web app em browser	hub-web-browser
Koder Talk	App mobile iOS em celular	talk-mobile-ios
Koder Talk	App TV TizenOS	talk-tv-tizenos
Koder Kortex	Backend Linux em servidor	kortex-backend-linux
Koder Koda	Engine embedded em Go runtime	kode-engine-go

2. Distinção de termos relacionados

Termo	Eixo	Exemplo
Variante	Distribuição (surface × target × form factor)	hub-cli-linux
Release / versão	Tempo (sequência de mudanças)	Hub v2.3.0
Artefato	Arquivo entregue (build output)	hub_2.3.0_amd64.deb
Componente	Código-fonte deployável	products/dev/hub/app/cli/
Sector	Identidade L3 do produto	products/dev/hub

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:

Surface	L4 origin	Descrição
mobile	app/mobile/	App Flutter touch-first
desktop	app/desktop/	App Flutter com mouse+teclado
tv	app/tv/	App JS/React com remote
web	app/web/	App em browser (PWA, SaaS)
cli	app/cli/	Comando não-interativo
tui	app/tui/	Terminal UI interativa
backend	backend/	Servidor HTTP/gRPC/WebSocket
engine	engine/	Biblioteca embarcável

3.2 — Target (eixo de plataforma/SO)

Target	Aplicável a surface
linux	desktop, cli, tui, backend, web (server-side)
macos	desktop, cli, tui
windows	desktop, cli, tui
android	mobile
ios	mobile
tizenos	tv
webos	tv
browser	web (qualquer Chrome/Edge/Firefox/Safari)
universal	engine (multi-language binding agnóstico de SO)

3.3 — Form factor (eixo de dispositivo)

Form factor	Surface típica
phone	mobile
tablet	mobile, desktop (iPad com keyboard)
tv	tv
laptop	desktop, web
desktop (workstation)	desktop, web
terminal	cli, tui
server	backend
embedded	engine

4. Combinações válidas

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

Surface	Targets válidos	Form factors típicos
mobile	android, ios	phone, tablet
desktop	linux, macos, windows	laptop, desktop, tablet (iPad)
tv	tizenos, webos	tv
web	browser	laptop, desktop, tablet, phone
cli	linux, macos, windows	terminal, server
tui	linux, macos, windows	terminal
backend	linux	server
engine	universal	embedded, server, terminal, laptop

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