# Shared Contracts

Esta pasta existe para concentrar contratos e artefatos compartilhados entre:

- `app/` (produto)
- `admin_app/` (administrativo)

Ela nao deve receber regra de negocio do atendimento nem codigo acoplado ao hot path do produto.

## Contratos iniciais

Nesta fase, os primeiros contratos compartilhados sao:

- `access_control.py`
  - define a hierarquia inicial de acesso interno
  - papeis: `colaborador`, `diretor`
  - `colaborador` consulta o fluxo operacional e cadastra novas tools em draft
  - `diretor` revisa, aprova, publica tools e cadastra novos colaboradores

- `tool_publication.py`
  - define o contrato minimo de publicacao de tools do `admin` para o `product`
  - inclui envelope de publicacao, status de ciclo de vida e schema de parametros

- `product_operational_data.py`
  - define quais datasets operacionais do `product` podem ser consultados pelo `admin`
  - explicita dominios, granularidade de leitura, campos permitidos e campos bloqueados
  - reforca que o acesso administrativo nasce como leitura orientada a relatorios
  - declara que a leitura deve acontecer por `admin_read_model`, com consistencia eventual e sem query direta do painel no banco operacional do produto
  - formaliza a materializacao inicial por `etl_incremental` em `snapshot_table`, servida por `dedicated_view`
  - deixa explicito que a fase inicial nao usa replica operacional do produto para abrir dashboards administrativos

- `system_functional_configuration.py`
  - define quais configuracoes funcionais o `admin` pode consultar e quais podem ser alteradas
  - separa o runtime do bot de atendimento do runtime de geracao de tools
  - estabelece catalogo homologado de modelos, politicas do bot, politicas de canal e estado efetivo publicado
  - reforca que apenas `diretor` altera configuracoes governadas com `manage_settings`
  - deixa explicito que o painel nao altera segredos, credenciais ou tabelas operacionais do produto

- `bot_governed_configuration.py`
  - detalha quais campos do bot ficam sob governanca administrativa
  - cobre selecao de modelo, geracao de resposta, uso de tools, fallback, handoff e operacao por canal
  - deixa explicito que a governanca do bot usa publicacao versionada e nao escrita direta no runtime do produto
  - reforca que runtime de geracao de tools nao e configuracao do bot de atendimento

- `model_runtime_separation.py`
  - formaliza que atendimento e geracao de tools usam perfis de modelo distintos
  - separa config key, catalogo alvo, publicacao e rollback entre os dois runtimes
  - deixa explicito que uma mudanca em um runtime nao propaga automaticamente para o outro

## Regras

- `shared/contracts` deve guardar apenas contratos estaveis entre servicos
- nada aqui deve importar modulos internos de `app/` ou `admin_app/`
- as mudancas devem ser additive-first para permitir deploy independente entre `product` e `admin`
- contratos de leitura operacional nao autorizam escrita administrativa nas tabelas do produto
- relatorios administrativos devem consumir read models assincronos, nunca scans pesados no hot path do atendimento
- views dedicadas de relatorio so podem ser construidas sobre snapshots sanitizados do admin, nunca sobre tabelas live do produto
- configuracoes funcionais governadas nao autorizam escrita direta no runtime do `product` durante request web do painel