Gleam.br Wiki

TOON | Wiki

Documentação de engenharia e especificações técnicas da Gleam-BR.

TOON

  • Oficial: https://toonformat.dev/
  • Github: https://github.com/toon-format/toon
  • Spec: https://toonformat.dev/reference/spec.html

A especificação TOON é a referência oficial para a implementação de codificadores, decodificadores e validadores. Ela define a sintaxe concreta, o comportamento normativo de codificação/decodificação e as regras de validação em modo estrito.

Você não precisa desta página para usar o TOON. Ela é voltada principalmente para implementadores e colaboradores. Se você deseja aprender a usar o TOON, comece com o guia de Introdução.

🌟 Gleam-BR: Utilização

Podemos utilizar este protocolo no momento de passar informações estruturadas para a AI LLM. A vantagem será reduzirmos o consumo de tokens p/ interpretar as informações passadas.

Atualmente, não temos nenhum projeto com esta implementação. Teremos que analisar utilzarmos algum NIF Rust, ou *implementar o protocolo em Gleam puro*.

JSON-Schema

  • Spec: https://github.com/json-schema-org/json-schema-spec

O JSON Schema é um vocabulário que permite validar, anotar e manipular documentos JSON.

Este repositório contém os códigos-fonte do trabalho em andamento para o próximo conjunto de documentos de rascunho da Internet (I-D) do JSON Schema da IETF. Para obter os I-Ds mais recentes, consulte a página de especificações no site.

🌟 Gleam-BR: Utilização

*Projeto*:

Estamos utilizando um gerador de códigos Gleam p/ gerar as definições do MCP diretamente da orgigem ModelContextProtocol.

Atualmente não temos a implementação que faz o download da especificação MCP em formato JSONSchema, mas já possuimos a forma de realizar a geração de código através de um arquivo, ver em ./priv. O código existente em gbr_json/src/gbr/json/schema/load somente consegue gerar o código Gleam da especificação 2025-06-18, temos bugs para resolver antes de gerarmos as novas definições MCP, 2025-11-25, em gbr_mcp/src/gbr/mcp/gen/defs.gleam através do gbr_mcp/src/gbr/mcp/loader.

Temos alguns exemplos de como implementar um servidor MCP usando o gbr_mcp: - gbr_mcp/examples/mcp_hello_srv: Um servidor simples MCP respondendo "Hello, <param_name> World!". - gbr_mcp/examples/mcp_hello_srv: Um servidor que simula uma calculadora MCP.

JSON-LD

  • Oficial: https://json-ld.org/
  • Spec: https://www.w3.org/TR/json-ld/ - Tools: https://cbor.io/tools.html - Yaml-ld: https://w3c.github.io/yaml-ld/ - CBOR-ld: https://w3c.github.io/cbor-ld/ - rc: https://github.com/w3c/json-ld-rc/ - Streaming: https://w3c.github.io/json-ld-streaming/ - Star: https://json-ld.github.io/json-ld-star/: Extensão para [JSON-LD11], [JSON-LD11-API] e [JSON-LD11-FRAMINING] para permitir que arcos em um gráfico de dados vinculados sejam anotados usando o modelo [RDFStar].
  • Rust: https://docs.rs/dcbor/latest/dcbor/
  • Swift: https://github.com/BlockchainCommons/BCSwiftDCBOR
  • Misc: https://developer.blockchaincommons.com/dcbor/

JSON-LD é um formato de Dados Ligados leve. É fácil de ler e escrever para humanos. Baseia-se no já consagrado formato JSON e oferece uma maneira de facilitar a interoperabilidade de dados JSON em escala web. JSON-LD é um formato de dados ideal para ambientes de programação, serviços web REST e bancos de dados não estruturados, como Apache CouchDB e MongoDB.

CBOR-LD

  • https://github.com/w3c/cbor-ld/
  • https://github.com/spruceid/cbor-ld

CBOR é um formato compacto de serialização e mensagens de dados binários. Esta especificação define o CBOR-LD 1.0, um formato baseado em CBOR para serializar Dados Ligados. A codificação foi projetada para aproveitar o ecossistema JSON-LD existente, implantado em centenas de milhões de sistemas atualmente, para fornecer um formato de serialização compacto para aqueles que buscam esquemas de codificação eficientes para Dados Ligados. Ao utilizar esquemas de compressão semântica, é possível obter taxas de compressão superiores a 60% em comparação com esquemas de compressão generalizados. Este formato destina-se principalmente a ser uma forma de usar Dados Ligados em ambientes de programação com restrições de armazenamento e largura de banda, para construir protocolos de rede semânticos interoperáveis ​​e para armazenar Dados Ligados de forma eficiente em mecanismos de armazenamento baseados em CBOR.

🌟 Gleam-BR: Utilização

Podemos utilizar este protocolo para definirmos as ferramentas MCP, trazendo maior contexto semântico p/ a LLM poder decidir qual ferramenta deve executar.

Ainda não temos nenhum projeto para esta implementação, talvez seja interessante implementarmos este protocolo utilizando o atual ./libs/gbr_json que fornece funções utilitárias p/ encode e decode de paylods JSON.

DID: Digital Identity Decentralized

  • Oficial: https://identity.foundation/
  • Spec: https://www.w3.org/TR/did-1.1/
  • Trusted AI Agents: https://identity.foundation/working-groups/trusted-agents.html - O foco está em definir uma estrutura interoperável e com opiniões definidas para viabilizar agentes de IA confiáveis, que preservem a privacidade e sejam seguros. Esses agentes atuam em nome de usuários ou sistemas e exigem mecanismos robustos de identidade, autoridade e governança. - *Use Case:* https://alanhkarp.com/UseCases.pdf

Identificadores descentralizados (DIDs) são um novo tipo de identificador que permite a identidade digital verificável e descentralizada. Um DID refere-se a qualquer sujeito (por exemplo, uma pessoa, organização, coisa, modelo de dados, entidade abstrata, etc.) conforme determinado pelo controlador do DID. Ao contrário dos identificadores federados típicos, os DIDs foram projetados para serem desvinculados de registros centralizados, provedores de identidade e autoridades certificadoras. Especificamente, embora outras partes possam ser usadas para auxiliar na descoberta de informações relacionadas a um DID, o design permite que o controlador de um DID comprove o controle sobre ele sem a necessidade de permissão de qualquer outra parte. Os DIDs são URIs que associam um sujeito DID a um documento DID, permitindo interações confiáveis ​​associadas a esse sujeito.

Cada documento DID pode expressar material criptográfico, métodos de verificação ou serviços, que fornecem um conjunto de mecanismos que permitem ao controlador do DID comprovar o controle sobre o DID. Os serviços possibilitam interações confiáveis ​​associadas ao sujeito DID. Um DID pode fornecer os meios para retornar o próprio objeto DID, caso este seja um recurso de informação, como um modelo de dados.

ILPD: DAG-CBOR

  • Oficial: https://ipld.io/
  • Spec: https://ipld.io/docs/
  • Github: https://github.com/ipld/ipld

IPLD é um ecossistema de formatos e estruturas de dados para a construção de aplicações totalmente descentralizadas.

O objetivo do IPLD é viabilizar estruturas de dados descentralizadas que sejam universalmente endereçáveis ​​e vinculáveis, o que, por sua vez, possibilitará mais aplicações descentralizadas. Essas estruturas de dados endereçáveis ​​e vinculáveis ​​nos permitirão fazer com os dados o que URLs e links fizeram com as páginas web HTML.

Dizemos que IPLD é um ecossistema, e não um projeto ou uma biblioteca, porque esse ecossistema é sustentado por alguns conceitos e padrões que garantem a compatibilidade entre formatos e linguagens de programação.

Você encontrará diversas bibliotecas para trabalhar com IPLD. Você pode até criar algumas das suas próprias. Essa biblioteca faz parte do ecossistema IPLD e você agora faz parte da comunidade. Você não precisa ser um colaborador em um repositório na organização IPLD do GitHub para fazer parte dessa comunidade; você já está quase lá só por ter lido até aqui.

🌟 Gleam-BR: Utilização

*Resumo*: Utilizar p/: - Discovery - Interoperability - Access Controls (Auth and Authz) / Delegation - Human in the Loop Flows - Agentic Registries - Trust/Attestation Chains - Observability / Interpretability - Privacy Preserving Communication / Compute - Agent Governance / Policy - Human Experience

Como?

Nós estamos construindo uma malha P2P (Noise, Yamux, Kademlia). API Keys são centralizadas e dependem de um banco de dados de validação. Se o sistema é descentralizado, a segurança deve ser baseada em Criptografia Assimétrica (DIDs - Decentralized Identifiers).

*Como deve ser:* Quando o Nó A se conecta ao Nó B, o nosso protocolo Noise já troca chaves públicas (peer_id). O seu nó BPM só vai aceitar executar um fluxo se o peer_id do chamador estiver na lista branca (autorizado) ou se ele enviar um token assinado criptograficamente (JWT offline) provando quem ele é.

*Não precisamos de servidor de senhas!*

Questões?

  • Podemos utilizar o COSE+CWT (CBOR) ao invés do Noise p/ encapsular nosso DID? Nós podemos utilziar o Noise somente como criptografia de rede e o CWT como chave de identificação, nosso Identity Authorization Manager. Buscar mais informações e gerar um relatório detalhado do que faz cada tecnologia.

  • Quais as diferenças entre o Noise e o COSE? Eu sei que o Noise é a base da criptografia libp2p e deve ser mantido em nossa solução ./shared/gbr_p2p, e imagino que ele forneça funções de baixo nível. Já o COSE eu não conheço muito, mas imagino que faça algo parecido, criando uma camada de segurança criptográfica para o protocolo CBOR. Preciso buscar mais informações e fazer um comparativo.

Segurança: Identidade Descentralizada (DID) em Redes Distribuídas

*Brainstorm* Paralelismo com a *Hyperledger* é excelente. A Hyperledger Fabric, por ser focada no meio corporativo, lida com redes distribuídas e permissionadas através de um *MSP (Membership Service Provider)*, que é essencialmente uma Infraestrutura de Chaves Públicas (PKI) baseada em certificados X.509 tradicionais.

Mas nós (gleam-br) somos uma Skynet. Não queremos depender de Autoridades de Certificação (CAs) centrais (como a Verisign). Como ter segurança sem descentralizar na totalidade num primeiro momento?

**A Solução: A Arquitetura did:key acoplada ao Protocolo Noise** Nós já estamos a usar o protocolo Noise (o mesmo do Signal e do WhatsApp) para o handshake P2P. O Noise gera um par de chaves assimétricas (Pública/Privada) no momento em que o nó inicia.

  1. Vamos adotar o método **did:key** da W3C. Este método é um DID em que o identificador é literalmente a própria chave pública encriptada (ex: did:key:z6MkhaXg1NDNV...). Não precisa de base de dados, não precisa de blockchain.

  2. *Como funciona a autorização (VPC ou Global):* O seu nó BPM (o músculo) terá um arquivo de configuração local simples (uma allowlist ou um contrato no DuckDB) listando os did:key dos Oráculos autorizados a enviar comandos. Quando o Oráculo bate à porta via túnel Yamux, o handshake Noise prova matematicamente quem ele é. O BPM verifica a chave e autoriza. Zero servidores de identidade, zero senhas, 100% criptografia de curva elíptica.

CBOR: Concise Binary object Representation

  • Oficial: https://cbor.io/spec.html
  • Spec: https://www.rfc-editor.org/rfc/rfc8949.html
  • Spec(deprecated): https://www.rfc-editor.org/rfc/rfc7049.html

O *Parser CBOR* precisa banir floats ou tipificá-los como inteiros fixos (Fixed-point math).

É um formato de dados cujos objetivos de projeto incluem a possibilidade de tamanho de código extremamente pequeno, tamanho de mensagem relativamente pequeno e extensibilidade sem a necessidade de negociação de versão. Esses objetivos de projeto o diferenciam de serializações binárias anteriores, como ASN.1 e MessagePack.

Este documento torna obsoleto o RFC 7049, fornecendo melhorias editoriais, novos detalhes e correções de erratas, mantendo total compatibilidade com o formato de intercâmbio do RFC 7049. Ele não cria uma nova versão do formato.

Gleam-BR: Utilização

./shared/gbr_p2p - *ISOLAMENTO DE WORKFLOW:* Para cada requisição recebida via gbr_p2p (Stream Yamux), o supervisor spawna um novo Ator gen_statem isolado para gerenciar aquele DAG específico. - *SCHEMA VALIDATION WALL:* Antes de iniciar qualquer DAG, o payload CBOR de entrada DEVE ser validado via Pattern Matching. Lixo binário é descartado imediatamente, e o canal TCP encerrado. - *DETERMINISMO CBOR:* O contrato financeiro deve ser estritamente serializado como um Array Posicional CBOR (não dicionário/mapa) para garantir que o hash SHA-256 da assinatura seja idêntico no Cliente, Provedor e Nuvem.

// Mensagem serializada via CBOR para troca no stream Identify do Yamux
pub type IdentifyMessage {
  IdentifyMessage(
    protocol_version: String,
    agent_version: String,
    public_key: BitArray,
    listen_addrs: List(String),
    protocols: List(String),
    observed_addr: Option(String),
  )
}

./shared/gbr_p2p_mcp - Já existe uma tentativa de encaixarmos o CBOR-LD no nosso protocolo p2p mcp.

/// ## Representação Semântica (CBOR-LD Compatible)
///
/// Em conformidade com k-means.md, utilizamos IDs inteiros para tipos
/// ontológicos em vez de strings URLs para minimizar o overhead na borda.
pub type Tool {
  Tool(
    name: String,
    description: String,
    // @type mapeado para um vocabulário comprimido (ex: 204 = mcp:FinancialAction)
    semantic_type: Int,
    schema: String,
    provider_did: String,
    embedding: Option(List(Int)),
  )
}

./shared/gbr_p2p_gossibsub - Usamos para o CBOR posicional no evento do protocolo gossip.

// O Envelope do GossipSub (CBOR Posicional)
// [CID, HLC_phys, HLC_log, DID, State, Payload]
pub type GossipEvent {
  GossipEvent(
    cid: BitArray,
    hlc_p: Int,
    hlc_l: Int,
    did: String,
    state: Int,
    payload: BitArray,
  )
}

Futuro (Temos algo no presente, mas tem que ser refatorado) - **Cognição & Agentes (shared/gbr_p2p_mcp):** Criado com foco em DuckDB VSS, Sharding Semântico (CBOR-LD) e Semantic Router local. Temos que analisar se teremos a necessidade de criar um novo projeto que será nosso descobridor de ferramentas MCP usando cogniçao e p/ encontrar os agentes, e.g. gbr_p2p_mcp_dicovery. Assim, podemos deixar o projeto gbr_p2p_mcp somente com a implementação da camada de rede. - *DAG-CBOR:* Adotamos o CBOR (com suporte a Directed Acyclic Graphs via CIDs) como formato de primeira classe para o Model Context Protocol (MCP). O CBOR permite Pattern Matching nativo absurdamente rápido em Gleam/Erlang, tornando esquemas rígidos (como .proto) redundantes e mantendo o sistema ágil para atualizações estruturais ("Schema-less"). - *TOKENOMICS (DUAL-SIGNATURE):* 1. O fluxo financeiro não bate na Blockchain/ScyllaDB a cada passo. Ocorre via "State Channels" (Canais de Estado) na memória RAM. 2. O Agente (Cliente) envia um PaymentPayload CBOR assinado contendo um Nonce (contador anti-replay). 3. O Provedor (BPE) executa a tarefa. 4. O Provedor adiciona a sua própria assinatura Ed25519 sobrepondo o mesmo array CBOR (SignedVoucher). 5. O Provedor injeta este recibo com Assinatura Dupla no GossipSub para o Bridge Service liquidar no ScyllaDB global.

*Vusualização*

flowchart TD
    %% Declaração de Nós e Formatos (Blinda o parser contra caracteres especiais)
    subgraph Malha_P2P [Malha P2P de Borda: TCP/Yamux/Noise]
        A["Nó IoT / Mobile\nAgente FSM Cliente"]
        B(["Nó Desktop\nProvedor MCP / BPE"])
        C["Nó Servidor Local\nProvedor BPE"]
        D(("Rádio Mesh P2P"))
    end

    subgraph Nucleo_GKE [Núcleo GKE Nuvem: SaaS gleam-lang.com.br]
        E{"Bridge Service\nBloom Filters"}
        F[("Ledger ScyllaDB\nEventos BPE")]
        G["Compilador CBOR-LD\nGerador de Parquet"]
    end

    %% Ligações Lógicas (Arestas)
    A <-->|"Kademlia + RPC Yamux"| B
    B <-->|"RPC Yamux"| C

    A <-->|"GossipSub (CBOR)"| D
    B <-->|"GossipSub (CBOR)"| D
    C <-->|"GossipSub (CBOR)"| D

    D == "Ingress 1M req/sec" ==> E
    E -->|"CQL Batches"| F
    F -->|"Batch Job 6h"| G

    G -.->|"Distribuição IPFS/Bitswap"| A
    G -.->|"Distribuição IPFS/Bitswap"| B

COSE: Object Signing and Encryption

  • Spec: https://datatracker.ietf.org/doc/html/rfc8152

Concise Binary Object Representation (CBOR) é um formato de dados projetado para tamanho de código e tamanho de mensagem pequenos. Há necessidade da capacidade de ter serviços básicos de segurança definidos para este formato de dados.

Este documento define o protocolo CBOR Object Signing and Encryption (COSE). Esta especificação descreve como criar e processar assinaturas, códigos de autenticação de mensagens e criptografia usando CBOR para serialização. Esta especificação também descreve como representar chaves criptográficas usando CBOR

CWT: CBOR Web Token

-Spec: https://datatracker.ietf.org/doc/html/rfc8392

CBOR Web Token (CWT) é um meio compacto de representar declarações a serem transferidas entre duas partes. As declarações em um CWT são codificadas em (CBOR), e a Assinatura e Criptografia de Objeto CBOR (COSE) é usada para proteção de segurança adicional na camada de aplicação. Uma declaração é uma informação declarada sobre um sujeito e é representada como um par nome/valor, consistindo em um nome de declaração e um valor de declaração. O CWT deriva do JSON Web Token (JWT), mas usa CBOR em vez de JSON.

CDDL: Concise Data Definition Language

  • Spec: https://datatracker.ietf.org/doc/html/rfc8610

Convenção de notação para Express Concise Binary Object Representation (CBOR)

Este documento propõe uma convenção de notação para expressar estruturas de dados Concise Binary Object Representation (CBOR) (RFC 7049). Seu objetivo principal é fornecer uma maneira fácil e inequívoca de expressar estruturas para mensagens de protocolo e formatos de dados que usam CBOR ou JSON.

TZif: Como armazenar timestamp(data, time) no CBOR

  • Spec: https://datatracker.ietf.org/doc/html/rfc8536

Automatic Certificate Management Environment (ACME)

A Infraestrutura de Chaves Públicas usando certificados X.509 (PKIX) é usada para diversos fins, sendo o mais significativo a autenticação de nomes de domínio. Assim, as autoridades de certificação (ACs) na PKI da Web são confiáveis ​​para verificar se um solicitante de um certificado representa legitimamente o(s) nome(s) de domínio no certificado. Até o momento da redação deste documento, essa verificação é feita por meio de um conjunto de mecanismos ad hoc. Este documento descreve um protocolo que uma AC e um solicitante podem usar para automatizar o processo de verificação e emissão de certificados. O protocolo também fornece recursos para outras funções de gerenciamento de certificados, como revogação de certificados.

← Anterior: Relatório de Arquitetura: Persistência de Estado Distribuído (BPMN/DMN) | WikiPróximo: Vanguarda Tecnológica: Agentes Semânticos | Governança →