Apêndice — Tipos de Nó e Regras do Linter

Referência compartilhada pelo Modelador (Craft) e pela extensão do VS Code.

---

Tipos de nó

Nós de fluxo (paleta do editor visual)

Doze tipos aparecem na paleta, nesta ordem. A coluna "tipo na engine" é o valor type que vai para o JSON .kikwi.

#	Nome na paleta	Tipo na engine	O que faz
1	Início	DEFAULT_START_EVENT	Ponto de partida do processo. Acionado via API REST ou eventos do sistema.
2	Fim	DEFAULT_END_EVENT	Finaliza o fluxo atual.
3	Decisão	EXCLUSIVE_GATEWAY	Avalia regras de negócio e segue por apenas um caminho verdadeiro. Exige que uma das saídas seja o fluxo padrão.
4	Divisão Paralela (Split)	PARALLEL_GATEWAY	Divide o fluxo em dois ou mais caminhos simultâneos.
5	Ponto de Encontro (Join)	JOIN_GATEWAY	Pausa e aguarda todos os caminhos paralelos chegarem antes de seguir.
6	Tarefa Externa (Espera)	EXTERNAL_TASK	Pausa o processo esperando uma resposta de fora (aprovação humana, webhook).
7	Tarefa Executável	EXECUTABLE_TASK	Roda lógica de negócio no backend, automática, sem pausar o processo.
8	Captura de Evento (Chave Única)	EVENT_CATCHER (catchType: STANDALONE)	Pausa e aguarda um evento externo correlacionar uma chave de negócio.
9	Captura de Evento (Grupo)	EVENT_CATCHER (catchType: GROUP)	Pausa e aguarda N eventos correlacionados (scatter-gather); política ALL ou ANY.
10	Tarefa Temporizadora	TIMER_TASK	Nó de fluxo principal que pausa até um prazo resolvido e então segue pelas próprias saídas.
11	Call Activity (Subprocesso)	CALL_ACTIVITY_COORDINATOR	Inicia uma ou mais instâncias de outro processo (por chave) e só segue quando todas concluírem.
12	Lançador de Evento	EVENT_THROWER	Resolve uma chave de correlação e a entrega internamente, sem pausar. Contraparte da Captura de Evento; falha se ninguém aguardar a chave.

As Captura de Evento (Chave Única) e (Grupo) são dois itens de paleta distintos que viram o mesmo type: "EVENT_CATCHER" no JSON, diferenciados pelo campo catchType.

Eventos de borda (boundary events)

Não vêm da paleta — são anexados a um nó já existente pelos botões no card do nó ou pelo Inspector. Contando-os como tipos de nó próprios, o vocabulário .kikwi tem 15 tipos:

Tipo na engine	O que faz
BOUNDARY_INTERRUPTIVE_TIMER	Prazo que interrompe a atividade a que está anexado quando expira, desviando o fluxo.
BOUNDARY_NON_INTERRUPTIVE_TIMER	Prazo que dispara um caminho paralelo sem interromper a atividade (ex.: lembrete de SLA).
BOUNDARY_ERROR_HANDLER	Captura um erro de negócio (um errorCode) lançado pela tarefa e desvia o fluxo. Um handler por errorCode.
BOUNDARY_INTERRUPTIVE_CATCH_EVENT	Aguarda um evento correlacionado que interrompe a atividade quando chega.

Regra de modelagem de erros. Um erro de negócio é sempre um BOUNDARY_ERROR_HANDLER anexado à tarefa que falha — nunca um EXCLUSIVE_GATEWAY comutando sobre um "motivo de falha". Um gateway só pode rotear sobre um valor que já foi calculado com sucesso.

Matriz de anexação validada pelo linter

Quais eventos de borda cada nó de fluxo aceita (regra KIKWI-013):

Nó de fluxo	Eventos de borda aceitos
Tarefa Executável	BOUNDARY_ERROR_HANDLER, BOUNDARY_NON_INTERRUPTIVE_TIMER
Tarefa Externa	BOUNDARY_NON_INTERRUPTIVE_TIMER, BOUNDARY_INTERRUPTIVE_TIMER, BOUNDARY_INTERRUPTIVE_CATCH_EVENT
Captura de Evento (Chave Única / Grupo)	BOUNDARY_NON_INTERRUPTIVE_TIMER, BOUNDARY_INTERRUPTIVE_TIMER
Tarefa Temporizadora	BOUNDARY_INTERRUPTIVE_CATCH_EVENT
Call Activity (Subprocesso)	BOUNDARY_INTERRUPTIVE_TIMER, BOUNDARY_NON_INTERRUPTIVE_TIMER
Lançador de Evento	(nenhum)

Início, Fim e os gateways não aceitam eventos de borda.

---

Regras do linter

O linter roda a cada alteração no editor visual (Craft web e VS Code). Cada regra tem um ruleId KIKWI-0XX.

Severidade error impede uma exportação limpa. Severidade warning é recomendação.

Regra	Severidade	Título	O que aponta
KIKWI-001	warning	Nó Desconectado	O nó não está conectado a nada; será ignorado pela engine na execução.
KIKWI-002	error	Nome de Tarefa Vazio	Tarefas e gateways precisam de nome descritivo (não o nome técnico do tipo) para o fluxo e os logs fazerem sentido.
KIKWI-003	error	Caminho sem Saída	O nó precisa ser conectado a um próximo passo ou a um evento de fim (exceto o próprio Fim).
KIKWI-004	warning	Configuração Pendente	Tarefa executável ainda sem um Executor (bean) configurado. Um dev precisa configurar antes do fluxo ir ao ar.
KIKWI-005	error	Evento de Início Inválido	O processo precisa ter exatamente um evento de início.
KIKWI-006	error	Conexão Quebrada	Uma conexão aponta para um nó que não existe mais no grafo.
KIKWI-007	error	Fluxo Padrão Ausente	Gateway exclusivo sem fluxo padrão (default) — se nada casar em runtime, o processo falha.
KIKWI-008	error	Rotas de Gateway em Conflito	Gateway exclusivo com mais de um default, ou duas saídas com a mesma resposta esperada.
KIKWI-009	error	Split/Join Incompleto	Split paralelo sem join correspondente (ou vice-versa) — a engine não resolve o ramo.
KIKWI-010	error	Política de Retry sem Máximo de Tentativas	retryPolicy declarado sem maxRetries — a engine trata silenciosamente como zero tentativas.
KIKWI-011	error	Call Activity Incompleta	calledElement é obrigatório; usar elementVariable exige collectionVariable.
KIKWI-012	error	ID de Nó Duplicado	Dois ou mais nós com o mesmo ID — a exportação sobrescreveria um deles silenciosamente.
KIKWI-013	error	Evento de Borda Não Suportado	Evento de borda anexado a um tipo de nó que a engine não aceita (ver matriz acima).
KIKWI-014	error	Estratégia de Resolução Incompleta	Uma estratégia (BEAN / VARIABLE / STATIC / TEMPLATE) foi escolhida, mas o campo correspondente está vazio.
KIKWI-015	warning	Ramo de Gateway Sem Rótulo	Um ramo de saída de gateway exclusivo sem rótulo — quem lê o diagrama não sabe qual condição leva por esse caminho.
KIKWI-016	error	Junção com Múltiplas Saídas	Um gateway de junção tem mais de uma aresta de saída — a junção deve seguir por exatamente um fluxo.
KIKWI-017	error	Declaração de Variável Inválida	Variável do catálogo com key vazia/inválida/repetida, label vazio ou formato desconhecido.
KIKWI-018	error	Opções de Select Inválidas	Opção única/múltipla sem opções, com value vazio ou repetido — ou opções num formato que não é select.
KIKWI-019	error	Monetário Sem Moeda	Variável MONEY sem currency ISO-4217 válida.
KIKWI-020	error	Regex de Validação Inválido	validationRegex que não compila, com mais de 512 caracteres, ou fora de texto curto/longo.
KIKWI-021	error	Vínculo com Variável Não Declarada	O nó vincula (variableBindings) uma key que não está no catálogo, ou a mesma key duas vezes na lista.
KIKWI-022	error	Entradas em Tarefa Executável	EXECUTABLE_TASK só aceita outputs — não há ator fornecendo dados.
KIKWI-023	warning	Variável Não Usada	Declarada no catálogo, mas nenhum nó a vincula nem referencia (providerVariable, collectionVariable, templates…).

KIKWI-017 a KIKWI-022 espelham as regras de deploy KIKWI-060 a KIKWI-065 do motor: um .kikwi sem erros nessas regras não é rejeitado no deploy por causa do catálogo de variáveis (ver Catálogo de Variáveis e Formulários). KIKWI-023 existe só no modelador.

:::note Linter de modelagem ≠ validação de deploy Estas regras validam a modelagem no editor, antes do .kikwi sair da ferramenta. A engine tem, separadamente, um validador de deploy (DeployValidator) com seu próprio catálogo — ver Regras de Processo Válido —, aplicado quando o processo é implantado. As duas camadas se complementam; não são a mesma lista, e a numeração é independente: KIKWI-005 do linter e KIKWI-005 do deploy são regras diferentes. :::