# 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:

```yaml
mappings:
  guardrail.dlex_in: GRL.004
```

A forma rica adiciona `action` e `aliases`:

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