Por que

Equipes, de pessoas ou de agentes, acumulam conclusões: "o retry é idempotente", "decidimos três tentativas". Elas moram em atas, tickets e memórias de conversa, e perdem três coisas pelo caminho: a fonte, a data da conferência e o que depende delas. Um texto convincente sem nenhuma das três passa em qualquer revisão apressada.

O KG-SSOT trata isso como problema de formato, não de disciplina. O conhecimento vive num grafo .kg.yaml, versionado junto do código, e um contrato formal decide no CI o que reprova:

• um nó confirmed ou de produção sem proveniência reprova (o que não tem fonte recuperável se declara unverifiable);
• uma fonte que é só um marcador (unknown, n/a, tbd) reprova;
• uma aresta que aponta para o nada reprova, e um nó solto também;
• um carimbo de verificação sem alvo, uma decisão sem origem e uma produção apoiada só em relato alertam.

Comece em 60 segundos

git clone https://github.com/marciocar/kg-ssot && cd kg-ssot
python3 -m venv .venv && .venv/bin/pip install --require-hashes -r tools/requirements.txt

# a suíte de conformidade contra o leitor de referência
.venv/bin/python3 -I tools/kg_conformance.py | tail -2

# um grafo válido e um que reprova
.venv/bin/python3 -I tools/kg_validate.py \
  spec/conformance/fixtures/latest/form/minimal/valid-minimal.kg.yaml \
  spec/conformance/fixtures/latest/form/minimal/bad-node-missing-label.kg.yaml

latest: 261/261 (reprova)
optional: 10/24 (só reporta)
PASSA   spec/conformance/fixtures/latest/form/minimal/valid-minimal.kg.yaml
REPROVA spec/conformance/fixtures/latest/form/minimal/bad-node-missing-label.kg.yaml
  MUST   form.required.node.label ×1
· 2 arquivos; 1 passam no MUST; 0 com aviso SHOULD (kg-contract-v4.schema.json + kg-contract-v4.should.schema.json)

Para usar como comando, biblioteca ou servidor MCP, o mesmo kit sai no PyPI: pip install kg-ssot traz os comandos kg-validate, kg-conformance, kg-gate, kg-store, kg-mcp e kg-prov-export, com o contrato e a suíte dentro do pacote. Em JavaScript, npm install kg-ssot traz o leitor JS, com o validador pré-compilado que roda também no React Native e no Expo. Para um cliente de MCP como o Claude Desktop, o servidor sai também como MCP Bundle (.mcpb). Para levar o gate a um repositório seu, o caminho é o vendor por tag, no capítulo 6 do manual.

Um nó, por dentro

- id: C_RETRY_SAFE
  node_type: claim
  plane: PROD
  status: confirmed
  impact: 4
  confidence: 0.8
  label: O retry do pagamento é idempotente.
  verified_at: "2026-10-01"
  verified_against: tests/payment_retry_test.py
  provenance:
    source: tests/payment_retry_test.py
    locator: test_retry_is_idempotent
    method: "medição: teste de integração no CI"

O label é o fato, curto. A provenance diz de onde ele veio e como: medição, leitura, juízes, derivado ou testemunho. O carimbo diz quando foi conferido e contra o quê.

Como funciona

flowchart LR
  subgraph produto["Produto (uma tag kg-ssot-vX.Y.Z)"]
    C["Contrato<br/>JSON Schema MUST + SHOULD<br/>+ regras de integridade"]
    S["Suíte de conformidade<br/>261 casos em dados puros"]
    R["Leitor de referência<br/>kg_validate.py"]
    S -- "todo leitor passa" --> R
    C --> R
  end
  subgraph adotante["Repositório adotante"]
    V["vendor/kg-ssot<br/>+ carimbo sha256"]
    G["kg_gate.py no CI<br/>catraca por grafo"]
    K[".kg.yaml do time"]
    V --> G
    K --> G
  end
  produto -- "kg_vendor.py update --tag" --> V
  G -- "nada piora:<br/>grafo novo passa,<br/>dívida só encolhe" --> PR["PR aprovado"]

1. O contrato é JSON Schema 2020-12 em dois níveis: MUST reprova, SHOULD alerta. As regras que o schema não alcança (ids únicos, pontas existentes, nó órfão) são parte dele.
2. A suíte é a prova de compatibilidade: cada caso é um arquivo YAML real com o veredito e os códigos esperados, e o leitor passa só se emitir exatamente os mesmos códigos.
3. O kit leva o contrato a um repositório por tag, com um carimbo que reprova edição local, e roda a catraca por grafo no CI: o que já reprovava vira dívida nomeada, um grafo novo tem de passar, e a dívida só encolhe.

Recursos

O que o KG-SSOT não é

Estado e próximos passos

• Vigente: contrato v4, release kg-ssot-v4.9.1. O leitor de referência passa em 261 de 261 casos de latest/.
• Em uso: um adotante de produção valida os grafos dele no CI pela catraca do v4. O critério de "estável" é 30 dias de uso contínuo sem mudança que quebre, e esse relógio fecha em 2026-11-08.
• Próximo: o v5 passa a reprovar o method fora da forma <classe>: <detalhe>, que hoje só alerta.
• Aberto: a camada semântica (frescor, contradição, completude de domínio) está em optional/, e o leitor de referência não a implementa: passa só nos 10 casos válidos, e os 14 que esperam um aviso ou uma reprovação semântica falham.

Documentação

Contribuir

Uma mudança no contrato começa por um caso de conformidade: o .kg.yaml que mostra o comportamento e o veredito esperado. As releases saem como tags kg-ssot-vX.Y.Z do repositório de desenvolvimento, onde todo PR que toca spec/ ou tools/ roda a suíte e os testes do kit no CI. O espelho das releases guarda só o que cada tag leva, um commit por tag, e não recebe PR: uma proposta ou um defeito entra como issue, de preferência com o caso que o mostra. Um leitor em outra linguagem é bem-vindo: o capítulo 7 do manual diz como medi-lo.

Licença

O produto (o que a release leva, listado em spec/release.json: o contrato, a suíte, os casos .kg.yaml, o kit em tools/, o ADOPTING.md, este README e o manual) é Apache-2.0: LICENSE, com o escopo no NOTICE.

Os casos .kg.yaml da suíte são parte do contrato e seguem a Apache-2.0.

O repositório de desenvolvimento guarda também o framework Onion vendorizado, com licença própria: o código que executa segue MIT e o material de método segue CC BY-NC 4.0, cada um no seu arquivo de licença na raiz daquele repositório. Nada disso viaja na release.

_{O KG-SSOT nasceu dentro do framework Onion, que hoje o adota por tag, como qualquer outro adotante. O produto não depende dele.}