# Contratos Compartilhados E Hierarquia De Acesso

Este documento define os primeiros contratos compartilhados entre `orquestrador-product`
e `orquestrador-admin`, com foco especial na hierarquia de acesso do runtime administrativo.

## Objetivo

Criar uma base comum para:

- autenticacao e autorizacao administrativa
- publicacao de tools do `admin` para o `product`
- evolucao independente dos dois servicos sem acoplamento indevido

## Hierarquia inicial de acesso

Os papeis administrativos ficam centralizados em `shared/contracts/access_control.py`.

Hierarquia:

1. `viewer`
2. `staff`
3. `admin`

### `viewer`

Responsavel por leitura operacional.

Permissoes iniciais:

- `view_system`
- `view_reports`
- `view_audit_logs`

### `staff`

Responsavel por operacao interna e governanca de drafts.

Permissoes iniciais:

- todas as de `viewer`
- `manage_tool_drafts`
- `review_tool_generations`

### `admin`

Responsavel por configuracao, publicacao e gestao de acesso.

Permissoes iniciais:

- todas as de `staff`
- `publish_tools`
- `manage_settings`
- `manage_staff_accounts`

## Regras de desenho

1. Os papeis nascem em contrato compartilhado para que `admin` e `product` falem a mesma lingua.
2. O `product` nao usa essa hierarquia para atendimento ao cliente final.
3. O `admin` usa essa hierarquia para autenticacao, autorizacao e auditoria.
4. Toda evolucao deve ser additive-first para nao bloquear deploy independente.

## Contrato de publicacao de tool

O contrato inicial fica em `shared/contracts/tool_publication.py`.

Ele cobre:

- `ServiceName`
- `ToolLifecycleStatus`
- `ToolParameterType`
- `ToolParameterContract`
- `PublishedToolContract`
- `ToolPublicationEnvelope`

## Como isso sera usado depois

### No `orquestrador-admin`

- criar `StaffAccount`
- associar `StaffAccount.role`
- controlar acesso a UI, as rotas e a aprovacao de tools
- emitir `ToolPublicationEnvelope` quando uma tool for publicada

### No `orquestrador-product`

- consumir apenas tools publicadas
- validar status e versao do contrato recebido
- evitar dependencia do runtime do admin no hot path

## Proximos passos naturais

- criar a entidade `StaffAccount`
- plugar a role do usuario interno ao contrato compartilhado
- modelar a persistencia de drafts/publicacoes de tool