agent_contas/docs/OBSERVABILITY_CONTRACT_REGISTRY.md

Observability Contract Registry

config/observability_mapping.yaml é a única tabela usada pelo framework para duas responsabilidades relacionadas ao contrato externo:

1. traduzir nomes/códigos semânticos para labels exigidos pela observabilidade do cliente;
2. preservar ações legadas de guardrails (retry, handover, etc.) sem hardcode de nomes no Python.

A sintaxe v1 continua válida:

mappings:
  guardrail.dlex_in: GRL.004

A forma rica adiciona action e aliases:

mappings:
  guardrail.revprec:
    action: retry
    aliases: [REVPREC, TIM_REVPREC]

label é opcional. Quando ausente, o nome de observabilidade não é renomeado. action também é opcional.

Precedência de ação

Para uma decisão negada, o framework usa:

1. metadata.terminal_action retornado pelo rail;
2. on_deny do guardrails.yaml;
3. action resolvida pelo observability_mapping.yaml;
4. BLOCK como fallback fail-safe.

Isso mantém compatibilidade com rails internos e externos sem que OutputSupervisor ou ParallelRailExecutor conheçam nomes como REVPREC, CMP, SCO, GND, ATH ou HUMAN.

Aliases

Uma entrada guardrail.revprec é automaticamente resolvida também por REVPREC. Aliases explícitos permitem associar nomes externos ou históricos, por exemplo TIM_REVPREC.

Compatibilidade

Mappings escalares continuam funcionando sem alteração. Agentes que não habilitam o mapper continuam em passthrough e usam BLOCK para negações sem ação explícita.