orquestrador/docs/architecture/shared-contracts-and-access-hierarchy.md

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
• leitura operacional segura do admin sobre o product
• configuracao funcional governada entre admin e 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. colaborador
2. diretor

colaborador

Responsavel por operacao interna de acompanhamento e cadastro inicial de tools.

Permissoes iniciais:

• view_system
• view_reports
• view_audit_logs
• manage_tool_drafts

diretor

Responsavel por configuracao, aprovacao, publicacao e gestao de acesso interno.

Permissoes iniciais:

• todas as de colaborador
• review_tool_generations
• 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

Contrato de leitura operacional do produto

O contrato inicial fica em shared/contracts/product_operational_data.py.

Ele cobre:

• datasets operacionais que o admin pode consultar do product
• dominios atuais: inventory, sales, review, rental, conversation, integration
• granularidade inicial de leitura por registro e por agregado
• campos liberados para relatorio e operacao
• campos bloqueados quando carregam identidade do cliente, texto livre ou segredos operacionais
• estrategia de leitura por admin_read_model, consistencia eventual e leitura sem query direta do painel no banco operacional do produto
• estrategia de materializacao inicial por etl_incremental, persistida em snapshot_table e exposta ao painel por dedicated_view

Regra de permissao

A leitura desses datasets nasce sob view_reports.

Isso significa:

• colaborador pode consultar relatorios e snapshots operacionais
• diretor herda essa leitura
• a permissao nao autoriza escrita nem governanca sobre tabelas operacionais

Regra de minimizacao

Mesmo quando um dataset do produto entra na fronteira compartilhada, o admin nao recebe automaticamente todos os seus campos.

A fronteira correta eh:

• expor indicadores operacionais, ids tecnicos e chaves publicas necessarias ao relatorio
• bloquear cpf, email, external_id, payloads brutos, mensagens livres e identificadores sensiveis
• preferir agregados quando o mesmo objetivo nao exigir leitura linha a linha

Regra de isolamento do hot path

As consultas administrativas de relatorio nao devem ser executadas diretamente sobre as tabelas operacionais do produto a partir de uma request web do painel.

A fronteira correta eh:

• o product escreve estado operacional
• uma camada assincrona de etl_incremental materializa snapshots sanitizados no admin
• o painel e as APIs administrativas consultam dedicated_view construidas sobre esses snapshots
• nenhuma view administrativa pode apontar diretamente para tabelas live do product

Contrato de configuracao funcional governada

O contrato inicial fica em shared/contracts/system_functional_configuration.py.

Ele cobre:

• quais configuracoes funcionais o admin pode consultar do sistema
• quais configuracoes podem ser alteradas apenas por diretor
• a separacao entre runtime de atendimento e runtime de geracao de tools
• a diferenca entre estado governado no admin e estado efetivo publicado no product
• a proibicao de alterar segredos, infra e tabelas operacionais a partir do painel

Superficies iniciais declaradas

As primeiras configuracoes funcionais compartilhadas sao:

• allowed_model_catalog
• atendimento_runtime_profile
• tool_generation_runtime_profile
• bot_behavior_policy
• channel_operation_policy
• published_runtime_state

Regra de permissao

A leitura dessas configuracoes nasce sob view_system.

Isso significa:

• colaborador pode consultar configuracoes efetivas, catalogos homologados e estado publicado
• diretor herda essa leitura
• apenas diretor pode alterar configuracoes governadas, usando manage_settings

Regra de governanca

A fronteira correta eh:

• diretor altera apenas configuracoes funcionais governadas
• toda alteracao nasce como estado administrativo versionado
• o product consome apenas configuracao publicada e aprovada
• o painel nao altera segredos, variaveis de ambiente, credenciais, schema operacional ou comportamento interno sem governanca

Regra de separacao entre modelos

A escolha de modelo do bot de atendimento e a escolha de modelo para geracao de tools nao devem compartilhar a mesma chave de configuracao.

A fronteira correta eh:

• atendimento_runtime_profile governa o modelo que responde ao cliente final
• tool_generation_runtime_profile governa o modelo usado para gerar e validar tools
• cada perfil pode evoluir, ser auditado e ser publicado em ritmos diferentes

Contrato de governanca do bot

O contrato inicial fica em shared/contracts/bot_governed_configuration.py.

Ele cobre, em nivel de campo, quais configuracoes do bot de atendimento ficam sob governanca administrativa.

As primeiras superficies governadas sao:

• selecao de modelo do bot: provider, model_name
• geracao de resposta: temperature, max_output_tokens, prompt_profile_ref
• uso de tools: tool_policy_ref, max_tool_calls_per_turn, confirmation_policy
• fallback e handoff: fallback_mode, handoff_enabled, handoff_intents
• operacao por canal: enabled, maintenance_mode, default_route, operation_window_ref

Regra de permissao

A leitura dessas configuracoes continua sob view_system.

A alteracao governada continua restrita a diretor, com manage_settings.

Regra de fronteira

Esse contrato deixa explicito que:

• runtime de geracao de tools nao entra como configuracao do bot de atendimento
• o painel governa referencias e politicas funcionais, nao segredos nem infraestrutura
• nenhuma configuracao do bot e aplicada por escrita direta no banco ou runtime live do product
• toda mudanca passa por publicacao versionada e auditavel

Contrato de separacao entre runtimes de modelo

O contrato inicial fica em shared/contracts/model_runtime_separation.py.

Ele cobre:

• os alvos atendimento e tool_generation
• a config_key de cada runtime
• o servico consumidor de cada perfil de modelo
• a exigencia de publicacao e rollback independentes
• a proibicao de propagacao implicita entre os dois runtimes

Regra de fronteira

Esse contrato deixa explicito que:

• o runtime de atendimento e consumido pelo product
• o runtime de geracao e consumido pelo admin
• trocar um perfil nao troca automaticamente o outro
• os dois podem compartilhar um provedor homologado, mas nao compartilham estado de configuracao

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
• construir relatorios usando apenas datasets declarados no contrato compartilhado
• consultar read models administrativos em vez de tabelas live do produto
• governar configuracoes funcionais sem escrever diretamente no banco operacional do product

No orquestrador-product

• consumir apenas tools publicadas
• validar status e versao do contrato recebido
• expor fronteiras seguras para sincronizacao incremental dos datasets permitidos ao admin
• consumir apenas configuracoes funcionais publicadas e aprovadas
• evitar dependencia do runtime do admin no hot path

Proximos passos naturais

• criar rotas administrativas para relatorios
• criar rotas administrativas para configuracao funcional do sistema
• estruturar snapshots e views de vendas, arrecadacao e operacao
• manter a escrita administrativa fora das tabelas operacionais do produto