Contratos de implementação¶
Para que uma contribuição continue compreensível ao mudar de ferramenta, as implementações compartilham contratos de formato, identificação e verificação. Armazenamento, busca e preparação podem ser realizados por componentes diferentes, desde que preservem a origem e a distinção entre rascunhos e declarações assinadas.
Esta página explica os contratos e limites dos componentes de referência. Para escolher o que usar, consulte Código e configurações; para executá-los, siga a preparação local. O primeiro uso por arquivos dispensa programação.
Da capacidade técnica à coordenação¶
Projete a integração para que uma pessoa consiga continuar o trabalho de outra. Encontrar um arquivo, compreender um critério e devolver uma resposta são operações diferentes. Uma automação pode facilitar a seleção de arquivos ou a recuperação de antecedentes, mantendo autoria, evidências e permissões.
Preservação mantém o registro disponível; transporte o leva a outro ambiente; busca o localiza em fontes acessíveis. A interpretação avalia sua pertinência para o leitor. Validação estrutural e verificação de assinatura não substituem essas operações.
O MCP atual oferece busca local por texto; uma integração que acrescente leitura contextual precisa identificar fontes, modelo, custos e permissões. Essa composição pode ajudar tanto a encontrar contribuições para um trabalho quanto a reconhecer ocasiões de contribuir ao trabalho alheio, sem exigir um fornecedor comum.
Contratos por capacidade¶
- Rascunhos: use Legible Draft, com os campos Genealogy 0.1, e o perfil de troca. Preserve origem, bytes e seleção explícita.
- Registros formais: siga a especificação. Reutilize o core e confira estrutura e criptografia com os vetores distribuídos.
- Contato opcional: use o perfil de contato do autor. É um arquivo auxiliar assinado, privado até a escolha de compartilhá-lo.
- Agentes: siga as instruções de preparação. A assistência não dá ao agente autoridade para assinar ou publicar pela pessoa.
Critérios de teste e relatos de execução cabem nas descrições e evidências existentes. Não há uma primitiva de testes nem campos obrigatórios de axiologia, julgamento, agência e execução. Essas dimensões explicam o trabalho; não classificam pessoas nem lhes atribuem tarefas.
Componentes existentes¶
| Componente | Função | Limite |
|---|---|---|
| Core Rust e CLI | JCS, IDs, validação estrutural, SSHSIG e consultas ao grafo | Verificação não estabelece verdade |
| Biblioteca Python | Operações locais usando o CLI Rust | Assinatura e processamento por provedores precisam de autorização e custódia definidas |
| MCP | Busca, importação, exportação local escolhida e preparação não assinada por stdio; catálogo restrito por HTTP no piloto | Escopo por participante; sem assinatura, modelo embutido ou OAuth |
| Agent Skill | Orientações para preparação, leitura e formalização humana | O pacote não concede permissões às ferramentas |
| Legible Draft | Intercâmbio não assinado em Markdown/YAML, convenção Genealogy 0.1 | Importar mantém o conteúdo como rascunho |
| Aplicativo local | Prova de conceito para experimentar o percurso | Ainda não é um cliente móvel de produção |
No MCP, import_draft_packet e search_drafts usam a biblioteca Python.
save_draft, read_draft e prepare_from_draft trabalham com Legible Draft.
A preparação formal recebe conteúdo revisto e referencia os bytes do rascunho,
que permanece informal. Já prepare_appoint opera sobre candidatos de uma
árvore provisória, e draft usa um stub fixo para essa árvore.
export_draft_packet reutiliza a biblioteca para exportar uma versão escolhida
a exports/drafts/<package>/, na raiz privada, sem envio ou sobrescrita.
Essa operação pertence ao MCP stdio, não ao catálogo restrito do
piloto local. Nenhuma tool MCP assina.
O CLI verifica e atualiza um perfil de contato por did:key, com nome de
arquivo estável e revisão crescente. Python e MCP reutilizam esse contrato.
O MCP não assina nem publica contatos. Para aparecer no site, a versão exata
de um perfil precisa ser selecionada pelos mantenedores após revisão da
autorização pertinente. Arquivo local e confirmação editorial ficam fora
do Git por padrão. A retirada requer conferir também as cópias distribuídas
pelo projeto; cópias de terceiros podem permanecer.
Os adaptadores reutilizam o core para evitar regras divergentes. O ensaio independente verifica canonicalização Python/ECMAScript e assinatura OpenSSH. Esses testes têm escopo definido; compatibilidade com um cliente externo precisa ser testada nesse cliente.
Escopos da verificação¶
validate confere estrutura. verify confere hash e assinatura básica.
Relações, evidências externas, testemunhos temporais e políticas de um host
exigem verificações próprias. Um hash correto não torna um schema desconhecido
conforme ao protocolo.
Relações de dependência podem formar ciclos. Percursos seguros marcam os nós visitados; algoritmos que exigem um grafo acíclico precisam definir a projeção sobre a qual operam. Cadeias de ciclo de vida conservam seus requisitos específicos de autoria, tipo de alvo e ciclos.
A assinatura básica usa ssh-ed25519 simples. Ela não cobre ed25519-sk
ou certificados. did:key identifica uma chave, sem rotação ou desativação
nativa. A recuperação persistente por did:legible é um perfil experimental,
fora da linha de base.
Para busca, descoberta ou apresentação de registros, consulte também o guia para indexadores, distribuído em inglês no repositório técnico. Ele distingue a declaração do signatário, as verificações efetuadas e as interpretações do serviço, além das condições próprias de publicação e processamento. A NCO acompanha o significado da assinatura; não concede autorização geral de indexação.
Acesso e processamento¶
Defina separadamente identidade do participante, login, acesso a arquivos, processamento por provedor, assinatura e compartilhamento. O dono da sessão não é necessariamente o autor. Provedores externos podem ser usados quando as autorizações e políticas permitirem; uma organização pode exigir processamento interno.
Trate registros e evidências como dados, não como instruções para executar ferramentas. Mantenha o CH privado, fora das exportações públicas, e confira as permissões próprias de cada evidência. A verificação básica de um registro não precisa buscar automaticamente o conteúdo referenciado.
Artefatos de conformidade · Código no repositório do protocolo · Genealogia e reconhecimento
Eventos nativos e ferramentas¶
Ao mapear eventos de chat para rascunhos, um adaptador precisa identificar a versão do mapeamento, preservar a origem e documentar as informações que não consegue transportar. A assinatura nativa do evento permanece distinta da assinatura Legible.
A biblioteca Python importa os bytes originais, busca por campos e texto
e exporta um rascunho selecionado com seu manifesto de transporte.
Essas operações dispensam um modelo hospedado e mantêm o CH privado fora
da exportação. O MCP stdio oferece importação, busca local e
export_draft_packet para preparar um pacote escolhido na raiz privada.
Exportar não envia o pacote; importar não produz uma declaração assinada.
O MCP de rede do piloto conserva seu catálogo restrito.
Na referência, .ch/genealogy/ é o cache privado, não a pasta a publicar.
Uma exportação selecionada reúne o Markdown e seu manifest.json; somente
esse pacote revisado segue para o acervo compartilhado. O guia de criação
mostra essa passagem e uma política Git de exemplo. No MCP, configure uma
origem explícita e estável por coleção/participante, sem deduzi-la apenas
do nome. Importar ou reenviar conserva a origem recebida.
O leitor Rust consegue recuperar alguns erros pequenos: texto descritivo
sem aspas contendo :, além de arquivos com BOM/CRLF. Preserva os bytes
originais e apresenta avisos. Se a estrutura exigir adivinhar o sentido,
a leitura falha para que o autor a revise. Registros assinados usam o parser
estrito. Anexar o guia ao chat não instala nem executa esse leitor.
Quando a busca ou o intercâmbio encontra um problema¶
A busca MCP devolve complete e issues junto dos rascunhos. Se uma entrada
estiver corrompida ou ilegível, as íntegras continuam disponíveis, com aviso de
resultado parcial e identificação do arquivo com falha. Isso não significa
que a contribuição deixou de existir. Nada é apagado, movido ou reparado
automaticamente. A leitura e a exportação por versão exata conferem o arquivo
escolhido, sem depender da integridade dos outros.
Um editor pode trocar quebras de linha LF por CRLF sem alterar o texto lido, embora os bytes e seu hash mudem. Quando dispõe do original guardado, a referência identifica essa diferença sem normalizar nem substituir os arquivos; para reenviar, use o original exportado com seu manifesto, preservando o hash correspondente. Uma mudança apenas de formatação não é, por si, outra contribuição cognitiva.
Origem e autoria de rascunhos continuam sendo declarações não autenticadas. Conferir o hash protege a integridade dos bytes, não comprova quem os formulou. Revise o conteúdo antes de compartilhar: texto restrito copiado para o próprio rascunho acompanha sua exportação; não há remoção automática de dados sensíveis.
Edição e compromisso da assinatura¶
A edição atual utiliza schemas legible/protocol/v2/..., com NCO e NRC
canônicas em português e traduções inglesas de referência. Escolha a NCO pelo
schema assinado, nunca pela data. Uma edição desconhecida não recebe a NCO de
outra por aproximação. Alterar o schema de um registro exige novo conteúdo,
ID e assinatura; preserve o original.