Errors facet — index

errors specs/errors/README.kmd

Índice navegável (não-autoritativo) das specs de erro da Koder Stack. Cada conceito de erro — classes, severidade, identificadores, envelope, texto humano, captura, retenção, padrões de código — tem UMA spec dona. Este README mapeia "conceito → dono" para que ninguém reimplemente nem duplique. Ele NÃO define nada normativamente: a autoridade vive nas specs apontadas.

When this pattern applies

All triggers

Errors facet — index

Este documento não é normativo. É o mapa de "conceito de erro → spec dona". A regra vive em cada spec apontada. Princípio de policies/content-location.kmd: cada conceito tem um dono; quem cita, referencia por path.

Mapa conceito → dono

ConceitoSpec donaResumo
Classes/categorias (DL,UP,AU,NW,DB,UI,IO,PM,VL,XX)specs/errors/taxonomy.kmd §R1–R2Enum fechado + definição semântica + desempate
Severidade (fatal/error/warning/info)specs/errors/taxonomy.kmd §R3Escala fechada; is_fatal derivado
Retryability (retryable/not-retryable/conditional)specs/errors/taxonomy.kmd §R4Classificação; alinha com error-handling §R9
Fingerprint (agrupamento)specs/errors/taxonomy.kmd §R5Regra de composição p/ dedup
Identificador (<PRODUCT>-<CATEGORY>-<CODE>-<SEQ>)specs/errors/user-facing-messages.kmd §4Formato do Error ID
Envelope / objeto de erro (shape de wire)specs/errors/model.kmdCampos mín. + opc. + problem+json
Dados mínimos / complementares / regras de registro (no wire)specs/errors/model.kmd §R1–R3Contrato síncrono serviço↔cliente
Texto humano (mensagem + "Ver detalhes" + templates)specs/errors/user-facing-messages.kmd §1–3UI mobile/desktop/web/CLI
Captura / telemetria (Groups A–G, privacidade)specs/errors/reporting.kmdPayload assíncrono → reporter
Retenção (raw 7d / aggregated 24m)policies/error-reporting-retention.kmdJanelas de retenção
Padrões de código (wrapping, panic, boundary, sentinel)specs/code/error-handling.kmdErro internal entre funções
Registry por produto ((category,code)→…)<product>/docs/technical/errors.mdGera errors-catalog.md

Os três payloads de erro (não confundir)

PayloadQuandoDono
EnvelopeSíncrono, no momento da falha, serviço→clientemodel.kmd
TelemetriaAssíncrono, depois, app→reporter.koder.devreporting.kmd
Bloco de suporteManual, texto copiável, usuário→suporteuser-facing-messages.kmd §5

Fluxo de um erro (camadas)

serviço falha
  → error-handling.kmd  (wrapping internal, idiom de linguagem)
  → taxonomy.kmd        (classe + severity + retryable)
  → model.kmd           (envelope problem+json) ──sync──► cliente
                                                            → user-facing-messages.kmd (humaniza p/ UI)
                                                            → reporting.kmd (telemetria opt-in) ──async──► reporter
                                                                                                            → error-reporting-retention.kmd

Por que múltiplas specs (e não um mega-doc)

Single-source-of-truth ≠ single-document. Cada conceito acima muda em ritmo próprio (o texto humano evolui com UX; o envelope com contratos de API; a taxonomia raramente). Mantê-los em specs separadas com fronteira explícita é o SSOT — fundi-los acoplaria mudanças não-relacionadas. Este índice dá a visão unificada sem criar uma autoridade concorrente.

References