Errors facet — index

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

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

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

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

Payload	Quando	Dono
Envelope	Síncrono, no momento da falha, serviço→cliente	`model.kmd`
Telemetria	Assíncrono, depois, app→reporter.koder.dev	`reporting.kmd`
Bloco de suporte	Manual, texto copiável, usuário→suporte	`user-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.