Pular para o conteúdo

Governança

Company Brain governado

Consulte o portfólio governado da fábrica com citação, concessões e histórico append-only.

Uma projeção exata do portfólio

O Company Brain é a projeção exata e governada do que uma fábrica de software sabe sobre o próprio portfólio: produtos (prod), projetos (proj) e iniciativas (init). Ele não é a memória semântica do OrkMind, com coleções, tags e busca: vive em tabelas próprias no PostgreSQL e só responde o que um produtor autorizado gravou, citando a origem de cada item.

O modo context, a operação history e esta documentação estão na main do repositório, na seção Unreleased do CHANGELOG. Ainda não fazem parte de uma versão publicada no PyPI.

Contrato e API separados

O contrato orkmind.company-brain/v1 é o mesmo arquivo no OrkMind e no Orkastery, byte a byte. O sha256 dele sai em capabilities como contract_hash, e o Orkastery recusa um Brain com hash diferente. O envelope das chamadas é a API orkmind.company-brain-api/v1: operações novas entram nela de forma aditiva, sem mudar o contract_hash. O pacote de contexto e o history são dessa API.

A validação é estrita: campo desconhecido é recusado, o id começa pelo kind, proj só tem pai prod e init só tem pai proj. A falha sai como um código brain.*, sem eco do conteúdo.

Identidade do login, concessões explícitas

A identidade vem só do login autenticado no PostgreSQL, que o administrador do banco mapeia para um principal humano ou de serviço. Nenhum campo da requisição, variável de ambiente ou argumento de ferramenta nomeia um principal. As concessões valem por tenant, principal e ACL, com ações, recursos, instâncias de origem, campos visíveis e validade; a revogação vale na chamada seguinte.

  • get, query e history são só de principal humano.
  • ingest, migrate e rollback são só de principal de serviço.
  • Sem a concessão da ação, a leitura responde como se a entidade não existisse.

Operações pela CLI e pelo MCP

orkmind brain request lê um envelope JSON no stdin e escreve a resposta no stdout; a ferramenta MCP orkmind_brain recebe o mesmo envelope. A DSN vem de ORKMIND_DATABASE_URL e o tenant de ORKMIND_BRAIN_TENANT; nenhum argumento escolhe banco ou identidade. As operações são capabilities, get, query, history, receipts, head e ingest. Os estados de resposta são ok, empty, unknown, withheld, forbidden, unavailable e conflict.

echo '{"schema":"orkmind.company-brain-api/v1","operation":"capabilities"}' | orkmind brain request

Modo context: um pacote citável

Uma seleção com mode context monta no servidor o pacote orkmind.company-brain-context/v1: as entidades pedidas por id e os pais que a concessão deixa ver, cada uma com a citação inteira da fonte (autoridade, instância, referência, hash, versão e local). Tudo roda num instantâneo REPEATABLE READ, READ ONLY. O que não tem citação inteira vira lacuna tipada, sem conteúdo.

O digest é o sha256 do JSON canônico do pacote, sem horário: o mesmo estado dá o mesmo digest, e quem recebe recalcula. O OrkMind cita; o frescor contra a fonte é calculado por quem tem a fonte. Um OrkMind anterior a este modo responde brain.selection.context-unsupported.

  • entity.unknown: ausente, apagada ou sem a concessão get.
  • entity.withheld: retida pela ACL; só o id aparece.
  • citation.incomplete: a citação visível não está inteira, e o item não entra.
  • owner.unresolved, observed.unknown e recorded.unknown: item citado sem dono resolvido ou sem horário.

Histórico append-only

A operação history devolve as versões de uma entidade em ordem de sequência, com a origem de cada uma: evento, produtor, fonte citada, ciclo da fábrica, horário de gravação e a marca rolled_back. Nada apaga ou reescreve essas versões; numa entidade apagada, o tombstone é a última.

Exige a ação history, só de humano; sem ela, a resposta é unknown. Concessão que não mostra o campo source responde forbidden, porque versão sem origem não é citável. Os campos do corpo seguem os campos da concessão.

echo '{"schema":"orkmind.company-brain-api/v1","operation":"history","payload":{"tenant_id":"exemplo","id":"proj-exemplo","limit":50}}' | orkmind brain request

Escrita, migração e uso pelo Orkastery

A escrita é só do produtor de serviço: ingest confere sequência, autoria, versão e referências e grava projeção, histórico e recibos na mesma transação; o mesmo evento repetido devolve o mesmo recibo. A migração administrativa usa orkmind brain migration, com plano conferido por hash e rollback por compensação, sem restaurar o banco inteiro. O schema só é criado por uma operação administrativa explícita; uma consulta nunca migra.

No Orkastery, ork brain context pede o modo context, confere o pacote inteiro e acrescenta o frescor contra o portfólio local. Diante de um OrkMind sem esse modo, monta o pacote pelo caminho anterior, com query e get, e declara isso no pacote.