🌿 Apresentação

Você chegou ao PAEBIRU — Protocolo Assíncrono de Ecossistemas Biológicos para Infraestruturas Recursivas Universais. Esta documentação é a fonte canônica de verdade. Está organizada em três trilhas — escolha a que combina com o seu momento.

flowchart LR
    A[Quem é você?] --> B{Primeira vez?}
    B -- Sim --> C[🌱 Estou chegando<br/>README · MANIFESTO<br/>ROADMAP · SETUP]
    B -- Não --> D{Operando em campo?}
    D -- Sim --> E[🔧 Vou operar<br/>Runbooks · Flashing<br/>Observabilidade]
    D -- Não --> F[🛠️ Vou contribuir<br/>RSE · 4 Dogmas<br/>RFCs · Bounded Contexts]

🌱 Estou chegando

Você nunca trabalhou com o PAEBIRU antes — perfeito. Comece por aqui.

Glossário essencial — malha, GALS, Maturidade Causal, Algedonic, LandauerLedger, Estigmergia — definidos no Dicionário canônico. Volte a ele sempre que um termo parecer novo.

🔧 Vou operar

Você é operador de campo: o nó está implantado, o termostato está a 65 °C no armário de telecom e o pager tocou às 3h. Esta trilha é o seu manual.

Para o ciclo completo, comece pelo Caderno do operador.

🛠️ Vou contribuir

Você é engenheiro(a) — quer modificar o código, abrir uma RFC, ou entender a arquitetura. Esta trilha é o seu guia.

Para entender a forma do organismo:

• Arquitetura em Bounded Contexts
• Realidade fractal
• Sistema celular
• SO distribuído

Para entender o porquê teórico:

• Arquitetura cognitiva
• Protocolos de coordenação
• Fundamentos termodinâmicos

🗺️ Onde encontrar o quê

📐 Convenções editoriais

Esta documentação segue convenções estritas (§9 do AGENTS.md):

• kebab-case em nomes de arquivo (exceção: rfcNNN_*.md).
• Metadados em comentários HTML (<!-- title: ... -->), nunca em frontmatter YAML — o mdBook renderiza YAML como texto visível.
• Caminhos relativos em todos os links. Caminhos absolutos são proibidos (a CI quebra o build).
• Diagramas em Mermaid (code-first), não imagens binárias.
• Português brasileiro (pt-BR) como idioma principal; termos técnicos canônicos são obrigatórios.

🌐 Onde nos encontrar

• Homepage: https://paebiru.org
• Repositório canônico: https://github.com/paebiru/paebiru
• Issues & RFCs: https://github.com/paebiru/paebiru/issues
• Segurança (vulnerabilidades): ver SECURITY.md ou e-mail direto (canal privado, sem abrir issue pública)

📜 Manifesto

Por que construir outra plataforma de computação distribuída quando já temos tantas? Esta é a resposta em sete teses.

Tese 1 — Soberania é um problema arquitetural, não político

A soberania computacional não emerge de declarações: emerge de decisões de projeto. Se a sua identidade mora em um servidor de CA privado, a sua soberania é a soberania daquele operador. Se a sua chave mora na sua cabeça ou no seu TPM, a sua soberania é sua.

PAEBIRU assume soberania por design:

• Identidade enraizada em hardware (TPM 2.0, Secure Enclave).
• Criptografia pós-quântica como linha de base, não como migração futura.
• Zero-Trust como postura default, não como feature configurável.

Tese 2 — A biologia já resolveu quase tudo

A natureza roda, há 4 bilhões de anos, uma rede distribuída com:

• 10³⁰ ~ 10³¹ células vivas, sem nenhum CEO.
• Tráfego massivo de informação (sinapse, hormônio, quórum), sem backbone central.
• Resiliência a perda de nós (apoptose, necrose, regeneração).
• Identidade verificável (sistema imune) sem autoridade emissora global.

PAEBIRU estuda esses mecanismos em vez de reinventar:

• Metabolismo → backpressure e LandauerLedger.
• Imunidade → MacrophageVM e síntese de anticorpos (plasmídeos WASM).
• Estigmergia → coordenação indireta via receipt e rastro ambiental.
• Homeostasia → sensores algedônicos em cada escala, sem supervisor global.

Tese 3 — O nó mais simples deve ser o mais simples possível

Se um sensor LoRaXBee com 32 kB de RAM não consegue participar da malha como igual, o sistema não é distribuído — é centralizado com participação periférica. O PAEBIRU é executável, sem std, em:

• ATmega 328P (8 bits, 2 kB RAM) — via paebiru-hal com heapless.
• ESP32, STM32, nRF52 — Cortex-M com FPU.
• RISC-V rv32imc (energy harvesting).
• x86 / arm64 em servidores e mainframes.

A mesma malha fala com todos; cada um fala só o que sua banda permite.

Tese 4 — Coordenação sem carona (anti-padrão “Costura”)

Bounded Contexts se comunicam por artefatos imutáveis com receipt, nunca por Arc<Mutex<T>> cruzando a membrana. “Costura” — acoplamento por tipo ou estado compartilhado — é sintoma de fronteira mal colocada.

A regra é cirúrgica: refatore a membrana antes de adicionar mais código. Nenhum patch que costure contextos é aceito.

Tese 5 — Tempo é maturidade, não cronologia

Ordenação de eventos usa Dotted Version Vectors (DVV) e Maturidade Causal, não Instant::now(). Em regime futuro (Dança Politemporal), Δt ∝ ΔS/γ — o tempo “congela” na ausência de variação entrópica.

Isso não é teoria: é a única forma de coordenar agentes que vivem em redes com partições, drift de relógio e backpressure variável sem liveness falso-positivo.

Tese 6 — A energia é a moeda primária

Computação não é gratuita. Cada ciclo é um joule subtraído do planeta, e cada joule é mensurável, debitável e auditável. O LandauerLedger transforma esse débito em receipt verificável — a base do crédito mútuo e da Loteria Joule (tópico em formalização).

A Loteria Joule não é uma metáfora: é o mecanismo pelo qual o sistema recompensa quem contribuiu com poder computacional real, em ordem causal, e cobra de quem drenou a malha.

Tese 7 — A fractalidade é restrição, não estética

O ciclo ingerir → metabolizar → excretar repete-se em 7 escalas — bit físico → neurônio LIF → função WASM → plasmídeo → nó ABAPORU → LocalSyncDomain → malha global. Esta é a Restrição Antropofágica (Realidade fractal — tópico em formalização):

• Mesma forma, em 7 escalas.
• Mesmas propriedades emergentes: homeostasia, algedonia, receipt.
• Mesmas ferramentas: Maturidade Causal, backpressure, estigmergia.

Quem viola esta restrição introduz uma articulação: a malha fica mais frágil, não mais rica.

Conclusão — Por que agora?

Porque a próxima década será de coordenação, não de comando. Porque infraestrutura crítica (saúde, energia, água, alimentos) precisa ser soberana por design, não por contrato. Porque o planeta não aguenta mais uma camada de abstração que ignora termodinâmica.

O PAEBIRU não é um produto. É um protocolo-cérebro — uma membrana metabólica entre humanos, dispositivos e a energia que os move. Se você concorda com pelo menos quatro destas teses, esta malha é sua também.

Veja também

• Roadmap — o como e o quando.
• Realidade fractal — a Tese 7 em detalhe.
• Fundamentos termodinâmicos — a Tese 6 em detalhe.
• Dicionário canônico — os termos que usamos.

🗺️ Roadmap

Quatro fases, da névoa à maturidade, com meta de finalização até 2026-12-31. Esta página é a fonte canônica de verdade sobre onde estamos e para onde vamos. O mapeamento granular por crate × fase está em Mapeamento do workspace.

Modo de operação: time pequeno + agentes de IA (Claude Code, Gemini CLI, kimi-cli, scripts) acelerando boilerplate, testes, documentação e verificação. Decisões arquiteturais e revisão continuam humanas. Veja CONTRIBUTING.md §3.

gantt
    title PAEBIRU · Roadmap 2026 (release v1.0.0 em 2026-12-31)
    dateFormat YYYY-MM-DD
    axisFormat %Y-%m
    section Fase 1 · Névoa
    Relé DHT autônomo              :active, p1a, 2026-06-05, 14d
    Edge scheduler + backpressure  :p1b, after p1a, 14d
    Island mode                    :p1c, after p1b, 14d
    section Fase 2 · Resiliência
    Identidade TPM 2.0 + quote     :p2a, after p1c, 14d
    FROST DPSS                     :p2b, after p2a, 14d
    WAL + tiering (C.A.P.I.B.A.)   :p2c, after p2b, 14d
    section Fase 3 · Economia
    Metering real (Landauer)       :p3a, after p2c, 21d
    Spot market + Loteria Joule    :p3b, after p3a, 21d
    Testbed físico (LoRa/Modbus)   :p3c, after p3b, 14d
    Chaos engineering              :p3d, after p3c, 7d
    section Fase 4 · Maturidade
    ML no scheduler (FLAIR)        :p4a, after p3d, 28d
    WASI-PAEBIRU ABI estável       :p4b, after p4a, 21d
    Certificações HW (CE/FCC)      :p4c, after p4b, 28d
    Piloto (saúde / água / energia):p4d, after p4c, 14d
    section Release
    v1.0.0 · freeze + publish      :crit, r1, 2026-12-25, 7d

Cores no Gantt: vermelho = crítico (release), preenchido = em curso.

Estado atual: Fase 1 — Fundação da Névoa (em curso)

⚠️ O workspace Cargo desta release contém apenas apps/node e crates/kernel. Os demais 30 crates descritos no AGENTS.md são visão ratificada, mas ainda não implementados. Os agentes de IA estão acelerando a implementação seguindo o CONTRIBUTING.md e o skill paebiru-architect.

Política de release: não marque seu PR como v1 a menos que feche um ciclo ponta-a-ponta. Em caso de dúvida, consulte workspace-mapping.md.

Fase 1 — Fundação da Névoa (F1)

Janela: 2026-06-05 → 2026-07-10 (5 semanas) Status: em curso

Tema: conectividade básica, scheduling, observabilidade.

Objetivos:

• Relé autônomo via DHT — qualquer nó novo se anuncia e é descoberto.
• Edge scheduler com backpressure (token bucket, créditos).
• Island mode — operação isolada em cenários sem WAN.
• Observabilidade ponta-a-ponta (Jaeger + Prometheus + Grafana).

Marcos (gates de saída):

• 2026-06-19 Relé DHT: dois nós trocam pulse ponta-a-ponta via libp2p Kademlia.
• 2026-07-03 Edge scheduler: token bucket ativo; MetabolicAction::Saturated testado com proptest.
• 2026-07-10 Island mode: nó sobrevive 7 dias offline e drena backlog ao reconectar.

Critérios de saída (DoD da F1):

• Dois nós trocam receipts soberanos ponta-a-ponta, com PAEBIRU_SKIP_PF=false.
• Um nó sobrevive 7 dias sem WAN, drenando backlog ao reconectar.
• Dashboard Grafana exibe: latência, backpressure, LandauerLedger, alarmes algedônicos.
• Cobertura ≥ 90 % nos crates kernel e node.
• Compila para riscv32imc-unknown-none-elf e thumbv7em-none-eabihf.

Fase 2 — Resiliência e Multi-Tenancy (F2)

Janela: 2026-07-10 → 2026-08-21 (6 semanas)

Tema: quotas, attestation, secrets, WAL, tiering.

Marcos (gates de saída):

• 2026-07-24 Identidade TPM 2.0 com tpm2_quote; sem fallback em produção.
• 2026-08-07 FROST DPSS: 3-de-5 assinaturas; rotação testada (R003).
• 2026-08-21 WAL posix + tiering (quente → morna → C.A.P.I.B.A. → Oceano).

Critérios de saída:

• Identidade enraizada em hardware é verificável por qualquer nó sem CA.
• Recuperação de ledger após corrupção (R004) automatizada.
• 100 nós com quotas heterogêneas operam 30 dias sem deadlock algedônico.

Fase 3 — Economia Real e Hardware (F3)

Janela: 2026-08-21 → 2026-10-09 (7 semanas)

Tema: metering, spot market, drivers reais, testbed físico, chaos.

Marcos (gates de saída):

• 2026-09-11 LandauerLedger debitando em µJ (PAEBIRU_GATE_SECURITY_COST_MICRO_JOULES) por operação de portão.
• 2026-10-02 Spot market + Loteria Joule com compensação multilateral a cada 24h.
• 2026-10-09 Drivers LoRa SX1262 + Modbus RTU + CAN bus operacionais no testbed físico.

Critérios de saída:

• Um nó em campo com sensor LoRa+Modbus envia receipt soberano que outro nó consegue validar e usar como prova de crédito.
• Loteria Joule opera 90 dias sem inconsistência de soma zero.
• MacrophageVM captura um pacote malicioso real do testbed e gera anticorpo.

Fase 4 — Maturidade (F4)

Janela: 2026-10-09 → 2026-12-25 (11 semanas)

Tema: otimização, padronização, ecossistema.

Marcos (gates de saída):

• 2026-11-06 ML no scheduler (FLAIR/Ising, Langevin SGD) com ≥ 30 % de redução de latência P99.
• 2026-11-27 WASI-PAEBIRU ABI congelada (12 semanas de estabilidade).
• 2026-12-25 Certificações HW (CE, FCC, Anatel) iniciadas; piloto em 1 domínio público operando ≥ 30 dias.

Critérios de saída:

• WASI-PAEBIRU ABI congelada por 12 meses sem quebra.
• Piloto em 1 domínio público (saúde, água ou energia) operando ≥ 30 dias.
• 1 000 nós heterogêneos (ATmega → mainframe) na malha global.

Escopo de F4 comprimido: para fechar em 2026-12, reduzimos o critério “1 000 nós na malha” para uma meta de strain-test interno (≥ 100 nós simulados + 10 físicos). O marco de 1 000 nós reais fica para v2.0 em 2027-Q2. Veja RFC em formalização · Roadmap v1.

Release v1.0.0

Janela: 2026-12-25 → 2026-12-31 (1 semana, freeze)

Janela de code freeze + auditoria de segurança + publicação. Tudo o que não entrou até 2026-12-24 vira v1.1.0 em 2027-Q1.

Por que 6 meses é viável

• Agentes de IA (Claude Code, Gemini CLI, kimi-cli) aceleram tarefas mecânicas: scaffolding de crates hexagonais, geração de testes, escrita de docs, verificação de tipos, lint, cobertura.
• Skills versionadas (.agents/skills/paebiru-*) capturam o conhecimento de domínio e o tornam executável pelos agentes.
• Templates canônicos (TLA+, Lean 4, BC docs, RFCs) reduzem o tempo de “página em branco”.
• Política de imutabilidade relaxada durante a fundação — renumeração de RFCs DRAFT é permitida até ratificação.
• Cobertura ≥ 90 % é o gargalo real, não a velocidade de escrita: cada crate precisa de testes substanciais.

O que não está no escopo deste roadmap

• Bindings de 13 linguagens — apenas paebiru-c (estável) e paebiru-py (beta) entram em v1.0.0. Demais ficam para v1.1+.
• Hardware wallet de prateleira — F4 entrega apenas o design de referência; a produção fica para 2027.
• DAO on-chain — governança fica off-chain (FROST + assinaturas multi-partidárias) em v1.0; on-chain migra em v2.0.
• ML no scheduler além de FLAIR — a integração com modelos externos (Candle, LLMs locais) fica para v1.1+.

Como ler este roadmap

Versão: 2.0 · Última atualização: 2026-06-05 · Próxima revisão: quinzenal · Mudanças versionadas por git tag (roadmap-vN).

⚙️ Setup inicial

Do zero ao cargo run -p paebiru-node em 15 minutos se você está em Linux x86_64 com Nix. Outras plataformas exigem instalação manual das deps de sistema.

Caminho 1 — Nix (recomendado)

Obtém todo o toolchain: Rust nightly, TPM2-TSS, libbpf, CUDA opcional, cross-compile para RISC-V e Cortex-M, Python, Node, Zig, PHP, R, Ruby, .NET 8, JDK 17, Dart, Go. Reproduzível bit-a-bit entre máquinas.

Pré-requisitos

• Nix com flakes habilitados.
• ~3 GB de espaço em disco para o shell.

Comando único

git clone https://github.com/paebiru/paebiru.git
cd paebiru
nix develop               # entra no shell
make build                # build do workspace default
make test                 # roda a suíte

Ao entrar no shell você verá:

🌿 Bem-vindo ao ambiente de desenvolvimento PAEBIRU (Nix)
Rust: rustc 1.86.0-nightly (...)
TPM2-TSS e Vulkan configurados.

Dica (CI): use nix develop --command bash -c 'make pre-commit' em scripts de CI.

Caminho 2 — Manual (Debian / Ubuntu 24.04)

Use este caminho se você não pode instalar Nix. Leva ~30 min.

1. Dependências de sistema

sudo apt-get update
sudo apt-get install -y \
    build-essential git curl pkg-config \
    libbpf-dev clang llvm libtss2-dev libssl-dev \
    cmake

2. Rust (nightly)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env"
rustup toolchain install nightly --profile minimal
rustup component add rust-src rust-analyzer llvm-tools-preview clippy rustfmt
rustup target add riscv32imc-unknown-none-elf \
                thumbv7em-none-eabihf \
                wasm32-unknown-unknown

O rust-toolchain.toml na raiz fixa a versão exata do nightly. Não instale stable — o projeto usa Edition 2024 + features instáveis (no_std em MCUs).

3. Ferramentas Cargo

cargo install cargo-llvm-cov cargo-audit cargo-fuzz

4. Pre-commit

pip install pre-commit mdbook mdbook-mermaid
pre-commit install

5. Verificação

make check       # cargo check rápido
make test        # roda a suíte
make pre-commit  # hooks locais

Caminho 3 — macOS

brew install git pkg-config openssl@3 bpfcc libbpf llvm tpm2-tss
# ...em seguida o mesmo rustup/cargo install do caminho 2

macOS não suporta eBPF/XDP nativo. O Portão 1 (Load Shedder) é automaticamente desabilitado na detecção do Darwin; em produção, use um nó Linux como edge.

Caminho 4 — Windows (WSL2 recomendado)

A matriz de release é Linux-first. Windows é suportado via WSL2 (Ubuntu 24.04). O caminho nativo é experimental.

wsl --install -d Ubuntu-24.04
wsl
# dentro do WSL2, siga o Caminho 1 (Nix) ou 2 (manual)

Variáveis de ambiente

Subir um nó local

cargo run -p paebiru-node

Saída esperada (em ~5 s):

NODE  Iniciando PAEBIRU Node (Trilha de Aço)...
NODE  Ponta-a-ponta rodando. Aguardando descoberta de peers...

Em outro terminal:

make test-local     # ciclo de vida ponta-a-ponta
# ou
curl http://localhost:1975/healthz

Para parar: Ctrl-C. O nó faz shutdown gracioso, fechando receipts em aberto e liberando peers.

Próximos passos

• 🌱 Primeiros passos — primeiro plasmídeo.
• 🔧 Caderno do operador — se você vai operar.
• 🛠️ Processo RSE — se você vai contribuir.

Solução de problemas

Se persistir, abra issue no GitHub com a saída completa de nix develop --command bash -c 'make pre-commit 2>&1'.

⚙️ Instalação

O PAEBIRU utiliza um toolchain moderno baseado em Rust Nightly e Nix. Se você já tem o Nix instalado, o processo leva menos de 5 minutos.

🚀 Caminho Rápido (Nix)

Recomendado para Linux e macOS. O Nix garante que você tenha as versões exatas de todas as dependências, incluindo compiladores para sistemas embarcados.

1. Instale o Nix (se ainda não tiver):

   curl -L https://nixos.org/nix/install | sh
   

2. Habilite Flakes (adicione ao seu ~/.config/nix/nix.conf):

   experimental-features = nix-command flakes
   

3. Entre no ambiente:

   git clone https://github.com/paebiru/paebiru.git
   cd paebiru
   nix develop
   

Ao entrar, você verá a mensagem: 🌿 Bem-vindo ao ambiente de desenvolvimento PAEBIRU (Nix)

🛠️ Caminho Manual (Ubuntu/Debian)

Se preferir não usar Nix, você precisará instalar as dependências de sistema e o Rust manualmente.

1. Dependências de Sistema

sudo apt update
sudo apt install -y build-essential git curl pkg-config libbpf-dev clang llvm libtss2-dev libssl-dev cmake

2. Rust Nightly

O PAEBIRU exige a edição 2024 e funcionalidades instáveis do Rust.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup toolchain install nightly
rustup default nightly
rustup target add riscv32imc-unknown-none-elf thumbv7em-none-eabihf wasm32-unknown-unknown

✅ Verificação

Para garantir que tudo está funcionando, rode o comando de verificação rápida:

make check

Se o comando terminar com Finished, seu ambiente está pronto para a Próxima etapa.

❓ Problemas comuns

• libbpf não encontrada: Certifique-se de instalar libbpf-dev.
• Erro de target: Verifique se você adicionou os targets riscv32 e thumbv7 via rustup.
• TPM2: Em máquinas virtuais, o suporte a TPM2 pode falhar; isso não impede o desenvolvimento inicial, mas é necessário para identidade soberana em produção.

Para um guia exaustivo de variáveis de ambiente e suporte a outras plataformas (Windows/macOS), veja o Setup Detalhado.

🧬 Primeiro plasmídeo

No PAEBIRU, a lógica de aplicação não vive em servidores centrais, mas em plasmídeos — pequenos módulos WASM que viajam pela malha e são executados pelos nós.

🧐 O que é um plasmídeo?

Inspirado na biologia, um plasmídeo é uma unidade auto-contida de código e dados.

• Definição: Escrito em uma DSL (Domain Specific Language) baseada em TOML ou HCL.
• Execução: Compilado para WebAssembly (WASM) e executado de forma isolada (sandbox).
• Distribuição: Propagado via GossipSub para os nós interessados.

📝 Definindo o plasmídeo

Um plasmídeo simples de “Hello Mesh” que emite um log quando recebe um pulso:

# hello_mesh.toml
[plasmid]
name = "hello-mesh"
version = "0.1.0"
author = "Soberano <node@exemplo.org>"

[behavior]
on_pulse = """
    log::info("Olá, malha! Recebi um sinal de {}", context.sender);
"""

🛠️ Ciclo de Vida

1. Sintetizar: O comando paebiru plasmid build converte o TOML em um binário .wasm.
2. Assinar: O plasmídeo é assinado com sua identidade soberana (Portão 3).
3. Injetar: Você injeta o plasmídeo no seu nó local.
4. Propagar: O nó anuncia o novo plasmídeo para a vizinhança causal.

🛡️ Segurança (Zero-Trust)

Antes de ser executado por qualquer nó, o plasmídeo passa pelo ZeroTrustPipeline:

• Portão 5: Validação semântica do contrato de dados (CDDL).
• MacrophageVM: Execução em quarentena para análise de comportamento.

🏁 Parabéns!

Você completou a trilha de Primeiros Passos. Agora você entende a visão, instalou o ambiente, subiu um nó e conhece as ferramentas de gestão e computação do PAEBIRU.

Para onde ir agora?

• 🛠️ Guia do Contribuidor — se quer ajudar a construir o core.
• 🔧 Caderno do Operador — se vai gerenciar infraestrutura.
• 🏛️ Arquitetura — para entender os fundamentos profundos.

🛠️ Forge CLI

A Forge CLI (paebiru-cli) é a canivete suíço do ecossistema PAEBIRU. Ela permite gerenciar identidades, monitorar nós em tempo real e realizar o flash de firmware em dispositivos embarcados.

📋 Visão Geral

A CLI foi projetada para ser tanto uma ferramenta de script quanto uma interface visual rica (TUI) para operadores de campo.

Comandos Planejados

🖥️ Interface de Terminal (TUI)

A Forge CLI incluirá uma interface baseada em ratatui que permite visualizar:

• Metabolismo do nó: Gráficos de CPU, memória e tokens de backpressure.
• Vizinhança Causal: Mapa de peers e latência causal.
• Landauer Ledger: Débitos e créditos energéticos em tempo real.

🔌 Flashing de Embarcados

Uma das funções críticas da Forge CLI é a preparação de MuleNodes. Através do comando flash, a ferramenta:

1. Detecta o hardware conectado (via USB/Serial).
2. Compila (se necessário) o firmware paebiru-hal para o alvo.
3. Grava o firmware e configura a identidade inicial no dispositivo.

⏭️ Próximos passos

Após entender as ferramentas de gestão, você está pronto para escrever seu Primeiro plasmídeo.

🌐 Olá, malha

Agora que você tem o ambiente configurado, vamos subir seu primeiro nó e conectá-lo à malha do PAEBIRU.

🚀 Subindo o nó

Para rodar o nó padrão (paebiru-node), utilize o Cargo. O nó iniciará os subsistemas de rede (libp2p), o Kernel (loop GALS) e a API de observabilidade.

cargo run -p paebiru-node

O que esperar na saída

Você verá logs estruturados indicando a inicialização:

NODE  Iniciando PAEBIRU Node (Trilha de Aço)...
NODE  Ponta-a-ponta rodando. Aguardando descoberta de peers...
API   Servidor HTTP rodando em http://127.0.0.1:1975

✅ Verificando a saúde do nó

Em outro terminal, você pode verificar se o nó está respondendo corretamente através do endpoint de saúde:

curl http://localhost:1975/healthz

Saída esperada: OK

📡 Descobrindo a malha

A descoberta opera em duas camadas:

• mDNS (local) — plug-and-play em LAN, sem configuração. Outros nós na mesma rede local são descobertos automaticamente.
• Kademlia DHT (global) — descoberta na malha pública. Configurável via PAEBIRU_BOOTNODES. Sem bootnodes, o nó opera em Island Mode e só descobre pares via mDNS.

Quando peers são descobertos (por qualquer das camadas), o nó se conecta via gossipsub ao tópico paebiru-metabolism e começa a trocar mensagens de PulseRequest e PulseResponse. Veja a entrada “Pulse” no Dicionário canônico para a definição completa.

Configuração de bootnodes

A variável de ambiente PAEBIRU_BOOTNODES aceita uma lista CSV de multiaddrs libp2p:

export PAEBIRU_BOOTNODES="/ip4/1.2.3.4/tcp/4001/p2p/12D3KooWPj...,/ip4/5.6.7.8/tcp/4001/p2p/12D3KooWQ..."
cargo run -p paebiru-node

Multiaddrs inválidos são descartados com warn! (o nó segue operando em modo degradado com os bootnodes válidos).

Você verá logs como:

KERNEL  Mensagem recebida de 7f3a1b2c: PulseRequest { timestamp: ... }
KERNEL  Enviando PulseResponse para 7f3a1b2c
NETWORK  Kademlia: nova rota para 12D3KooW... (1 addr(s))
NETWORK  Kademlia bootstrap OK — routing table populada

🛠️ Comandos úteis

⏭️ Próximos passos

Com o nó rodando, você pode explorar a Forge CLI para gerenciar sua identidade e interagir com a malha de forma mais avançada.

🔧 Caderno do Operador

Você é operador(a) de campo — implantou um nó, configurou o TPM, montou o armário de telecom, e o pager tocou às 3h da manhã. Esta página é o seu manual de bolso. Para o manual de cada incidente, veja os Runbooks.

Princípios

1. Nada se reza — tudo se mede. Antes de agir, leia o estado real do nó (/healthz, /metrics, logs estruturados).
2. Backpressure é mensagem, não erro. Se o LandauerLedger está vermelho, o sistema está te avisando — não force mais carga.
3. Receptor-reator. Cada ação sua é um ato metabólico na malha: emite um receipt. Se o receipt não voltar, refaça.
4. Mude a membrana, não o core. A maioria dos incidentes se resolve trocando adaptadores, não lógica de domínio.

Ferramentas essenciais

Áreas de runbook

• Runbooks — 11 incidentes canônicos
• Flashing embarcado — ESP32, STM32, RISC-V
• Observabilidade — Jaeger, Prometheus, Grafana
• Troubleshooting — sintomas × causas × ações
• Postmortems — análises de incidentes passados

Antes de pedir ajuda

Reúna:

1. Versão (paebiru --version).
2. PAEBIRU_STORAGE_PATH (anonimizado!).
3. Saída de paebiru node status.
4. Últimos 200 linhas de log do serviço.
5. Hash do commit (git rev-parse HEAD).
6. O que você mudou desde a última operação bem-sucedida.

Padrão de comunicação: abra uma issue com a tag operator-help e inclua o acima. Não cole segredos — apenas identificadores públicos de identidade (Peer ID em hex, não a chave privada).

Variáveis de ambiente canônicas

Regra de ferro: qualquer PAEBIRU_SKIP_* ligado em produção é veto algedônico — o nó se autodesliga após o alarme.

🔌 Flashing Embarcado

Guia para preparar e gravar o firmware PAEBIRU em dispositivos microcontrolados (MuleNodes).

1. Preparação do Toolchain

Certifique-se de ter os alvos Rust instalados:

rustup target add riscv32imc-unknown-none-elf thumbv7em-none-eabihf

Ferramentas de Gravação

• ESP32: espflash ou esptool.py.
• ARM (STM32/nRF52): probe-rs ou st-link.
• AVR: avrdude.

2. Compilando o Firmware

Navegue até o diretório do seu dispositivo ou use o paebiru-hal:

cargo build -p paebiru-hal --target <target-do-seu-hardware> --release

3. Realizando o Flash

Utilize a Forge CLI para automatizar o processo (recomendado):

paebiru flash --chip esp32s3 --port /dev/ttyUSB0

Ou manualmente via probe-rs:

probe-rs run --chip STM32F401RETx target/<target>/release/paebiru-hal

4. Configuração de Identidade Inicial

Após o flash, o dispositivo estará em modo de Provisionamento.

1. Conecte-se via Serial (115200 baud).
2. O dispositivo gerará um par de chaves inicial e exibirá o PeerID.
3. Utilize a CLI no seu computador para autorizar o novo nó na sua LocalSyncDomain.

5. Veja também

• BC HAL
• Runbook R001 · Boot
• Setup · Manual

📊 Observabilidade

O PAEBIRU fornece visibilidade total sobre o metabolismo dos nós e a saúde da malha através de padrões abertos.

1. Stack Recomendada

• Métricas: Prometheus (porta 1975 /metrics).
• Tracing: Jaeger (porta 4317 OTLP).
• Logs: Grafana Loki (logs JSON estruturados).
• Visualização: Dashboards Grafana (veja o diretório ops/grafana/).

2. Métricas Críticas

3. Distributed Tracing

Utilize o TraceID presente nos cabeçalhos das mensagens para rastrear o caminho de um plasmídeo através de múltiplos nós na malha global.

🔍 Troubleshooting

Guia rápido de sintomas e soluções para incidentes comuns.

Tabela de Sintomas

Logs Úteis

Procure por estas keywords nos logs:

• CRITICAL: Veto Algedônico iminente.
• SECURITY: Violação em algum dos 5 portões.
• RECOVERY: Reconstrução do estado causal em curso.

📜 Postmortems

Lista de incidentes históricos e o que aprendemos com eles para evoluir os Runbooks.

Histórico de Incidentes

(Esta seção será preenchida conforme a malha evolui)

[2026-06-01] Tempestade de Sincronização

• Sintoma: CPU em 100% em nós de borda durante reconexão após queda de WAN regional.
• Causa: Backpressure ausente no estágio de Correnteza.
• Correção: Implementado token bucket no sync da Pororoca Causal (RFC 019).
• Runbook Atualizado: R009 · Migração.

📋 R001 · Boot de nó em campo

Sintoma: O serviço paebiru-node não inicia, falha imediatamente após o boot ou entra em um loop de reinicialização.

flowchart LR
    S[paebiru-node não sobe<br/>ou reinicia em loop] --> D[Diagnóstico<br/>journalctl + cargo run + ss :1975]
    D -- Porta 1975 ocupada --> A1[Ação 1<br/>matar processo ou<br/>export PAEBIRU_API_PORT]
    D -- Storage sem perms --> A2[Ação 2<br/>mkdir + chmod 700<br/>~/.paebiru]
    D -- Falta de entropia<br/>pqcrypto panics --> A3[Ação 3<br/>instalar/configurar<br/>haveged]
    A1 --> V[Verifica<br/>curl :1975/healthz<br/>log: Ponta-a-ponta rodando]
    A2 --> V
    A3 --> V
    V -- OK --> End[Encerrar]
    V -- não resolveu --> Esc[Escalar<br/>issue operator-help]

🔍 Diagnóstico

1. Verifique os logs do sistema:

   journalctl -u paebiru-node -n 100 -f
   

2. Tente um início manual para ver a saída direta:

   cargo run -p paebiru-node
   

3. Verifique se a porta da API (1975) já está ocupada:

   ss -tulpn | grep 1975
   

🛠️ Ação

Causa 1: Porta Ocupada

Se a porta 1975 estiver em uso por outro processo:

• Ação: Mate o processo anterior ou altere a porta via variável de ambiente:

  export PAEBIRU_API_PORT=1976
  

Causa 2: Caminho de Armazenamento Inválido

Se o log indicar erro ao abrir o banco de dados ou identidade:

• Ação: Verifique as permissões de PAEBIRU_STORAGE_PATH (padrão ~/.paebiru):

  mkdir -p ~/.paebiru
  chmod 700 ~/.paebiru
  

Causa 3: Pânico de PQC (Criptografia)

Se o log mostrar erro em pqcrypto ou falta de entropia:

• Ação: Verifique se o sistema tem haveged ou similar para garantir entropia suficiente no /dev/random.

✅ Verificação

1. O comando curl http://localhost:1975/healthz retorna OK.
2. O log mostra: NODE Ponta-a-ponta rodando. Aguardando descoberta de peers....

🚨 Escalar

Se o nó continuar falhando após as ações acima, colete a saída de paebiru node status (se disponível) e abra uma issue com a tag operator-help.

📋 R002 · Identidade TPM

Sintoma: O nó falha ao carregar ou gerar a identidade soberana. Logs mostram erros como TPM Error, Permission denied on /dev/tpm0 ou Identity not found.

🔍 Diagnóstico

1. Verifique a existência do dispositivo TPM:

   ls -l /dev/tpm*
   

2. Verifique se o usuário tem permissão:

   groups $USER | grep tss
   

3. Teste as capacidades do TPM:

   tpm2_getcap properties-fixed | head -n 20
   

🛠️ Ação

Causa 1: Permissão Negada

Se /dev/tpm0 existir mas o acesso for negado:

• Ação: Adicione o usuário ao grupo tss (ou o grupo dono do device) e reinicie a sessão:

  sudo usermod -aG tss $USER
  

Causa 2: TPM Bloqueado (Dictionary Attack Lockout)

Se o TPM estiver em modo de bloqueio por muitas tentativas falhas:

• Ação: Aguarde o tempo de lockout ou, se tiver a senha de owner, faça o reset:

  tpm2_dictionarylockout --clear-lockout
  

Causa 3: Falta de suporte a PQC no TPM

Se o nó exige ML-DSA mas o TPM é antigo:

• Ação: O PAEBIRU tentará um fallback para armazenamento seguro via software se PAEBIRU_ALLOW_SW_IDENTITY=true estiver setado (não recomendado para produção).

✅ Verificação

1. Execute paebiru identity status.
2. O log deve mostrar: SECURITY Identidade carregada via HardwarePassport (TPM 2.0).

🚨 Escalar

Se o erro persistir, verifique a versão do firmware do TPM e consulte a RFC 007 sobre Identidade Soberana.

📋 R003 · Rotação de chaves FROST

Sintoma: Alerta de “Key Age Exceeded” ou perda de um ou mais shares de uma chave distribuída (threshold signature). O nó pode perder a capacidade de assinar transações se cair abaixo do threshold (ex: 3 de 5).

🔍 Diagnóstico

1. Verifique o estado das shares locais:

   paebiru identity check-shares
   

2. Verifique a conectividade com os outros guardiões:

   paebiru node peers | grep guardian
   

🛠️ Ação

Causa 1: Share Perdida ou Corrompida

Se uma share local foi deletada ou o hardware falhou:

• Ação: Inicie o protocolo de recuperação de share (DPSS) com o quorum restante. Você precisará de $t$ guardiões online.

  paebiru identity recover-share --threshold 3
  

Causa 2: Rotação Preventiva (Idade da Chave)

A política de segurança exige rotação a cada 90 dias.

• Ação: Inicie uma nova cerimônia FROST. O sistema gerará novos polinômios e distribuirá novas shares sem mudar a chave pública agregada (se usar resharing) ou gerando uma nova (se for migração total).

  paebiru identity rotate --ceremony-id <UUID>
  

✅ Verificação

1. paebiru identity status mostra “Shares: Healthy (3/5)”.
2. O próximo recibo gerado é assinado com sucesso.

🚨 Escalar

Se o quorum mínimo não for atingido, a chave está permanentemente perdida. Acione o Plano de Recuperação de Desastre (R011).

📋 R004 · Recuperação de ledger

Sintoma: Erros de I/O no C.A.P.I.B.A., falha na verificação de checksum de blocos, ou divergência causal (fork local). Logs mostram Corrupted block ou Hash mismatch.

🔍 Diagnóstico

1. Verifique a integridade do banco local:

   paebiru capiba check --full
   

2. Verifique se há espaço em disco:

   df -h $PAEBIRU_STORAGE_PATH
   

3. Identifique o último bloco válido:

   paebiru capiba last-valid
   

🛠️ Ação

Causa 1: Corrupção de Índice (Prolly Tree)

Se os dados estão lá, mas a árvore de busca está quebrada:

• Ação: Reconstrua os índices a partir dos blocos brutos (WAL).

  paebiru capiba rebuild-index
  

Causa 2: Blocos Faltantes ou Divergentes

Se o nó perdeu mensagens durante uma partição longa:

• Ação: Force uma ressincronização (Pororoca Causal) com um peer de confiança:

  paebiru capiba sync --peer <TrustedPeerID>
  

Causa 3: Falha de Hardware (Bad sectors)

• Ação: Mova o storage para um novo disco e restaure a partir do peer mais próximo ou do backup em Oceano.

✅ Verificação

1. paebiru capiba check retorna “Integrity OK”.
2. O nó volta a processar novos recibos normalmente.

🚨 Escalar

Em caso de divergência massiva de estado entre muitos nós, acione a governança econômica para um snapshot de consenso.

📋 R005 · Quarentena MacrophageVM

Sintoma: Logs do Kernel mostram SECURITY Package quarantined ou MacrophageVM: Antibody synthesized. O nó detectou uma mensagem suspeita e a isolou para análise.

🔍 Diagnóstico

1. Verifique o ID do pacote isolado:

   paebiru security quarantine-list
   

2. Inspecione o relatório de comportamento da VM:

   paebiru security report <PackageID>
   

🛠️ Ação

Causa 1: Falso Positivo (Plasmídeo Conhecido)

Se você confia na fonte e a VM foi muito conservadora:

• Ação: Libere o pacote manualmente e adicione a assinatura à lista de permissões local.

  paebiru security release <PackageID> --force
  

Causa 2: Ataque de Comportamento (Esgotamento de Memória)

Se o relatório indica que o pacote tentou alocar memória excessiva dentro da sandbox:

• Ação: O sistema gerará um Anticorpo automaticamente. Garanta que ele foi propagado:

  paebiru security broadcast-antibody <PackageID>
  

Causa 3: Divergência de Contrato (CDDL)

Se o pacote violou o esquema de dados do Portão 5:

• Ação: Rejeite permanentemente e notifique o emissor (se for um peer conhecido).

✅ Verificação

1. paebiru security status mostra “Quarantine: Empty”.
2. O rastro do anticorpo aparece nos logs do GossipSub.

🚨 Escalar

Se houver uma onda massiva de quarentenas de fontes diferentes, o nó pode estar sofrendo um ataque de dia zero coordenado. Acione o canal de segurança global.

📋 R006 · Atualização OTA

Sintoma: Nova versão de firmware disponível. O nó precisa ser atualizado remotamente (Over-The-Air) sem perda de identidade soberana ou estado causal.

🔍 Diagnóstico

1. Verifique a versão atual:

   paebiru --version
   

2. Verifique o status do binário de atualização:

   paebiru update check
   

🛠️ Ação

Causa 1: Atualização Menor (Patch)

• Ação: Execute a atualização automática. O nó fará o download, validará a assinatura ML-DSA do binário e reiniciará.

  paebiru update apply --version <Version>
  

Causa 2: Atualização de Kernel (Breaking Change)

Se a atualização altera o formato do DVV ou do banco de dados:

• Ação: Realize um snapshot do C.A.P.I.B.A. antes de prosseguir.

  paebiru capiba snapshot --path /mnt/backup/
  paebiru update apply --rebuild-index
  

✅ Verificação

1. O nó sobe e paebiru --version mostra a nova versão.
2. paebiru node status indica que os peers estão sendo redescobertos.

🚨 Escalar

Se o nó entrar em loop de boot após a atualização, utilize a ferramenta de Flash físico (R001) para reverter para a versão anterior preservando a partição de storage.

📋 R007 · Saturação XDP

Sintoma: O Portão 1 (Load Shedder) está descartando uma alta porcentagem de pacotes. Logs mostram XDP: Dropping packets due to rate limit ou Saturação do Portão 1.

🔍 Diagnóstico

1. Verifique a taxa de descarte:

   paebiru security metrics | grep xdp_drop_rate
   

2. Identifique a fonte do tráfego volumétrico:

   paebiru security top-talkers --gate 1
   

🛠️ Ação

Causa 1: Ataque DDoS Volumétrico

• Ação: Aumente a agressividade do rate limiting no kernel eBPF e bloqueie os IPs/PeerIDs agressores no Bloom Filter.

  paebiru security block-peer <AttackerID> --permanent
  

Causa 2: Erro de Configuração de Malha

Muitos peers tentando sincronizar simultaneamente.

• Ação: Ajuste os tokens de backpressure para suavizar a ingestão.

  export PAEBIRU_MAX_TOKENS=50
  

✅ Verificação

1. A taxa de descarte (drop rate) estabiliza abaixo de 5%.
2. A CPU do sistema (processamento eBPF) retorna a níveis saudáveis.

🚨 Escalar

Se a saturação ocorrer a nível de placa de rede (NIC) impedindo o acesso SSH/gerência, o nó deve ser isolado fisicamente do switch para limpeza de regras.

📋 R008 · Drift de relógio Langevin

Sintoma: O nó não consegue validar recibos de peers devido a “Causal Maturity Future Drift”. O tempo de Langevin do nó local está muito atrás ou muito à frente da vizinhança.

🔍 Diagnóstico

1. Compare o tick local com o tick da malha:

   paebiru entropy status
   

2. Verifique a variação entrópica (ΔS):

   paebiru entropy metrics
   

🛠️ Ação

Causa 1: Falta de Atividade Metabólica

O nó está “congelado” porque não processa eventos.

• Ação: Force um TriggerPulse para re-sincronizar o estado metabólico.

  paebiru node pulse --force
  

Causa 2: Partição de Rede Longa

O nó operou em “Ilha” por muito tempo.

• Ação: Inicie uma Pororoca Causal para puxar a maturidade dos vizinhos dominantes.

  paebiru capiba sync --strategy dominant-causal
  

✅ Verificação

1. paebiru entropy status mostra “Sync Status: Converged”.
2. Novos recibos são aceitos sem erros de maturidade.

🚨 Escalar

Se o drift for causado por falha no gerador de ruído gaussiano (falta de entropia de hardware), o nó deve ser reiniciado com drivers de entropia corrigidos.

📋 R009 · Migração para Oceano

Sintoma: O storage quente/morno (Nascente/Correnteza) está atingindo o limite de capacidade. O nó precisa mover dados antigos para o Tier frio (Oceano).

🔍 Diagnóstico

1. Verifique o uso de disco por estágio:

   paebiru capiba usage
   

2. Verifique a maturidade causal dos dados:

   paebiru capiba status --tier morna
   

🛠️ Ação

Causa 1: MUS (Minimum Useful Survival) Atingido

Dados excederam o tempo de vida útil garantido na memória quente.

• Ação: Dispare o processo de transmutação analítica para Parquet/Iceberg.

  paebiru capiba migrate --to oceano
  

Causa 2: Saturação de Disco Imediata

• Ação: Force a migração agressiva, priorizando dados com $\Delta C \to 0$ (baixa interação).

  paebiru capiba migrate --aggressive --min-interact 0
  

✅ Verificação

1. Espaço em disco na partição quente é liberado.
2. Os metadados dos blocos migrados aparecem no IcebergManifest.

🚨 Escalar

Se a migração para o Oceano (armazenamento externo/Filecoin) falhar, o nó ativará a Apoptose Saudável, deletando dados irrelevantes para preservar a Homeostasia do sistema.

📋 R010 · Falha de ZK-PoL

Sintoma: O nó não consegue gerar ou validar Provas de Localização (Portão 4). Mensagens são rejeitadas com erro ZK-PoL verification failed.

🔍 Diagnóstico

1. Verifique o backend de ZK:

   paebiru security status --gate 4
   

2. Teste a geração de prova simples:

   paebiru security test-pol
   

🛠️ Ação

Causa 1: Falta de Proximidade Geográfica

O nó está tentando assinar uma localização fora do raio permitido pelo contrato.

• Ação: Verifique se as coordenadas de referência (centros de quórum) estão atualizadas.

Causa 2: Erro de Setup Confiável (CRS)

Os parâmetros Groth16 local estão corrompidos.

• Ação: Baixe novamente o setup confiável oficial da malha.

  paebiru security refresh-crs
  

✅ Verificação

1. O comando paebiru security test-pol retorna “Proof valid”.
2. O nó volta a participar de rounds de aprendizado federado que exigem PoL.

🚨 Escalar

Falhas sistemáticas de ZK-PoL em múltiplos nós podem indicar um ataque de eclipse ou uma mudança não documentada no circuito do protocolo. Consulte a equipe de criptografia.

📋 R011 · Disaster Recovery

Sintoma: Falha catastrófica de hardware, perda total de dados locais ou roubo do dispositivo físico.

🛠️ Ação

Passo 1: Revogação de Identidade

Se o dispositivo foi roubado ou a chave comprometida:

• Ação: Use sua chave de backup (ou quorum FROST) para anunciar a revogação do PeerID na malha.

  paebiru identity revoke <OldPeerID> --reason compromised
  

Passo 2: Provisionamento de Novo Hardware

• Ação: Instale o OS, as dependências de sistema (R001) e o PAEBIRU Node.

Passo 3: Restauração de Identidade

• Ação: Importe seu HardwarePassport ou regenere as shares FROST a partir dos guardiões (R003).

Passo 4: Reconstrução do Estado Causal

• Ação: Puxe o histórico completo do Oceano e sincronize as últimas janelas Langevin com os vizinhos mais próximos.

  paebiru capiba restore --from-ocean
  paebiru node sync-all
  

✅ Verificação

1. O novo nó é reconhecido pela malha como o sucessor legítimo do nó anterior.
2. O LandauerLedger reflete o saldo histórico restaurado.

🚨 Escalar

Caso as chaves de backup e o quorum FROST também sejam perdidos, a soberania sobre aquela identidade é irrecuperável. Um novo PeerID deve ser gerado do zero.

🔬 Processo RSE — Research, Strategy, Execution

O ciclo RSE é o fluxo obrigatório de contribuição. Ele é simples, escasso em formalidade, e não pula para código. Agentes de IA que trabalham no PAEBIRU devem segui-lo: a skill paebiru-developer operacionaliza o ciclo inteiro.

flowchart LR
    A[Issue /<br/>necessidade] --> R[Research<br/>O que existe?]
    R -->|gaps| S[Strategy<br/>Onde colocar?]
    S -->|plano| E[Execution<br/>Cirurgia + testes]
    E -->|falhou| R
    E -->|passou| P[PR +<br/>checklist]
    P --> M[Maintainer<br/>merge]
    M -->|regressão| R

1. Research

Pergunta-guia: “O que já existe, o que falta, e quem tentou isso antes?”

Atividades:

1. Cite a fonte do problema. Issue? Runbook? RFC em DRAFT/PROPOSED? Bug? Postmortem? Sem fonte, a tarefa não é contribuição — é feature creep.
2. Mapeie os Bounded Contexts afetados. Para cada um, abra a BC doc correspondente em architecture/bounded-contexts/. Se não existir, a tarefa é primeiro escrever a BC doc.
3. Verifique o Dicionário canônico reference/dictionary.md para termos relevantes. Se um termo não estiver, adicione-o antes de propor código.
4. Leia a skill relevante em .agents/skills/ — ou paebiru-architect se for transversal.
5. Procure RFCs em formalização em rfc/README.md. Se a sua mudança intersecta um tópico, escreva a RFC primeiro ou espere a ratificação daquela.

Saída esperada: parágrafo de 5-10 linhas na descrição da issue ou do PR, respondendo:

• Qual problema está sendo resolvido?
• Quais BCs são afetados?
• Quais dogmas estão em jogo (4 Dogmas)?
• Quais termos do Dicionário precisam ser revisados/criados?
• Quais RFCs estão relacionadas ou em formalização?

2. Strategy

Pergunta-guia: “Onde colocar a mudança sem costurar contextos?”

Atividades:

1. Escolha a membrana certa. Se a mudança cruza dois BCs, você provavelmente está costurando — volte à fase 1 e reestruture. Em caso de dúvida, abra uma issue com a tag architect-help antes de prosseguir.
2. Defina a interface (port) antes da implementação. Traits em crates/<bc>/src/ports/ são a fronteira. Se a interface pública muda, é RFC obrigatória (ver §7 do CONTRIBUTING).
3. Liste os testes que vão cobrir a mudança. Mínimo:
   • 1 teste unitário por novo tipo/função pública;
   • 1 teste de integração se tocar actor/ ou adaptadores;
   • 1 teste property-based se tocar invariante (DVV, soma zero, Landauer, etc.);
   • 1 teste no_std se tocar Kernel/Math.
4. Identifique o gate de qualidade (ver quality.md):
   • Conformidade (lint, fmt, audit)?
   • GALS & Domínio (test, cobertura)?
   • Verificação formal (TLA+/Lean 4)?
   • Embarcada (no_std build)?
5. Documente o que pode dar errado. Liste 2-3 cenários de regressão e como o teste pega cada um.

Saída esperada: parágrafo de 5-10 linhas descrevendo:

• Em que BC/crate a mudança entra.
• Qual a nova interface (se houver).
• Lista de testes a serem escritos.
• Gate de qualidade aplicável.
• Riscos e mitigações.

3. Execution

Pergunta-guia: “Como implementar de forma cirúrgica e validável?”

Atividades:

1. Branches pequenos. Um branch por unidade lógica: feat/<bc>-<unidade>, fix/<bc>-<sintoma>, docs/<escopo>, rfc/<número>-<slug>.
2. Commits atômicos. Um commit por mudança conceitual. Mensagem em imperativo, assunto ≤ 72 chars, corpo que responde por quê (não o quê).
3. Validação local antes do push:

   make check         # tipos
   make lint          # clippy + fmt --check
   make test          # suíte
   make coverage      # ≥ 90 % de linhas
   make pre-commit    # hooks locais
   

4. Atualize o que mudou fora do código:
   • BC doc se a API pública mudou.
   • Dicionário se um termo novo entrou em uso.
   • Runbook se a mudança afeta operação.
   • CHANGELOG.md na seção Unreleased (categoria: Added/Changed/Fixed/Security/Removed).
5. PR com checklist completo. Use o template. Preencha:
   • Ciclo RSE (1-2 linhas cada).
   • 4 Dogmas preservados (declaração explícita).
   • Cobertura antes/depois.
   • RFCs citadas (se aplicável).
   • Atribuição correta (DCO Signed-off-by).

Saída esperada: PR aberto com CI verde, revisores marcados, descrição completa.

4. Review & Merge

Quem revisa: 1 mantenedor + 1 peer do BC afetado. Quem aprova: mantenedor com permissão de merge. Merge strategy: squash and merge por padrão, rebase and merge para séries de 1-3 commits coesos.

Checklist do reviewer:

• Código lê como a prosa do BC doc.
• Não há costura entre BCs.
• Não há Mutex/Arc<Mutex<>> cruzando fronteira.
• Não há std::time::Instant no domínio.
• Não há bloqueio dentro de loops de ator.
• Não há novos warnings de cargo clippy.
• Cobertura mantida (≥ 90 %).
• BC doc / Dicionário / CHANGELOG atualizados.

5. Anti-padrões de processo

6. Veja também

• Qualidade · 4 Dogmas + 4 Esteiras
• Verificação formal
• Mapeamento do workspace
• Escrevendo RFCs
• CONTRIBUTING.md §3 (RSE)
• Skill paebiru-developer

🛡️ Qualidade — 4 Dogmas + 4 Esteiras

A Muralha da Qualidade do PAEBIRU tem 4 dogmas (o que é inegociável) e 4 esteiras (como o gate é executado em CI). Nenhuma regressão chega a main sem passar por todas as 4.

flowchart TB
    A[PR aberto] --> E1[Esteira 1<br/>Conformidade]
    E1 -->|passa| E2[Esteira 2<br/>GALS & Domínio]
    E2 -->|passa| E3[Esteira 3<br/>Verificação Formal]
    E3 -->|passa| E4[Esteira 4<br/>Embarcada]
    E4 -->|passa| M[main]
    E1 -->|falha| X[bloqueado]
    E2 -->|falha| X
    E3 -->|falha| X
    E4 -->|falha| X

Os 4 Dogmas Inquebráveis

Originais do AGENTS.md §4, ratificados como princípio de revisão. Um PR que viola qualquer dogma é rejeitado mesmo que funcione.

🛡️ Dogma 1 — Isolamento Absoluto (Hexagonal)

“A lógica de domínio é o núcleo sagrado. Infraestrutura é detalhe injetado via traits.”

Invariantes:

• crates/<bc>/src/domain/ não importa de actor/, ports/ ou adapters/. Verificado por:

  grep -rE '^use crate::(actor|ports|adapters)' crates/<bc>/src/domain/
  # deve retornar vazio
  

• Toda dependência de I/O passa por trait declarado em crates/<bc>/src/ports/.
• Cruzamento entre BCs é via artefato imutável com receipt — nunca Arc<Mutex<T>> compartilhado.

Sinais de violação:

• use std::net, use std::fs, use std::time::Instant em domain/.
• tokio::spawn ou mpsc::channel em domain/.
• Estruturas do BC A importadas diretamente em BC B.

🌀 Dogma 2 — Paradigma GALS & Ator

“Localmente síncrono, globalmente assíncrono. Nunca bloqueie dentro do loop do ator.”

Invariantes:

• Loops de ator usam apenas mpsc::Receiver::recv().await, tokio::select! ou similar. Nenhuma espera bloqueante.
• Estado mutável do ator é dentro do struct do ator; nada de Mutex<DomainState>.
• Mensagens entre BCs são serializáveis (Serialize + Deserialize).

Sinais de violação:

• std::sync::Mutex, std::sync::RwLock no domínio ou no ator.
• thread::sleep, std::thread::join em código de runtime.
• Operações de I/O síncronas (std::fs::read, std::net::TcpStream) sem wrapper async.

⚙️ Dogma 3 — no_std First

“O código de domínio deve compilar sem a biblioteca padrão, do ATmega ao mainframe.”

Invariantes:

• crates/kernel/src/domain/ compila para riscv32imc-unknown-none-elf e thumbv7em-none-eabihf sem warnings.
• crates/math/ compila para os mesmos alvos.
• Coleções dinâmicas usam heapless em vez de Vec/HashMap no caminho embarcado.

Sinais de violação:

• use std::collections::* em código domain/.
• Alocação dinâmica (Box, Vec, String) em código no_std.
• Dependências que exigem std automaticamente.

🔌 Dogma 4 — Interoperabilidade Blindada (Opaque Handles & Zero-Copy)

“O FFI expõe apenas ponteiros opacos. Serialização pesada é substituída por vistas diretas da memória.”

Invariantes:

• Tipos públicos do crate expostos a FFI usam #[repr(C)] + ponteiro opaco (sem campos públicos).
• Buffers compartilhados via FFI são zero-copy (ponteiro + tamanho).
• serde_json/protobuf proibidos em crates/bindings/* para caminhos quentes.

Sinais de violação:

• Tipos Rust complexos visíveis no header C.
• serde_json::from_str em hot path de binding.
• Vec<T> retornado através de fronteira FFI (vira cópia).

As 4 Esteiras da Muralha

Cada esteira tem um critério de saída binário (passa/falha). CI enforça em ordem. Uma esteira só é avaliada se a anterior passou.

Esteira 1 — Conformidade (sintática, estática, segurança básica)

Ferramentas:

Saída da esteira: zero erros, zero warnings de clippy, zero CVEs HIGH/CRITICAL.

Esteira 2 — GALS & Domínio (testes + cobertura)

Ferramentas:

Saída da esteira: suíte verde, cobertura ≥ 90 %, sem teste flaky.

Esteira 3 — Verificação Formal (TLA+ + Lean 4)

Verificação cirúrgica: aplicada só onde a garantia supera o custo de modelagem. Detalhes em formal-verification.md.

Ferramentas:

Saída da esteira: modelos compilam, provas não regrediram, contradições detectadas resolvidas.

Esteira 4 — Embarcada (no_std)

Ferramentas:

Saída da esteira: build limpo para todos os alvos embarcados suportados pela mudança.

Tabela de mapeamento: dogma × esteira

Como aplicar este documento

• Autor do PR: percorra a tabela para o dogma que sua mudança toca. Cada dogma tem testes específicos em cada esteira.
• Reviewer: use a tabela como checklist de revisão.
• Agente de IA: leia a skill paebiru-architect antes de propor patches que tocam dogmas. Cite o dogma preservado no PR.

Veja também

• AGENTS.md §4 — Convenções de código
• Processo RSE
• Verificação formal
• CONTRIBUTING.md §2 — Princípios inegociáveis
• Dicionário · Maturidade Causal

🛡️ Verificação Formal

No PAEBIRU, a verificação formal não é um luxo acadêmico, mas uma ferramenta pragmática de engenharia. Utilizamos modelos formais para provar invariantes críticas de concorrência, economia e matemática.

1. Abordagem Pragmática

Não tentamos provar cada linha de código. Aplicamos a verificação cirurgicamente onde o custo da falha é alto ou o comportamento é complexo.

2. TLA+ (Temporal Logic of Actions)

Usado para modelar o estado global e a interação entre atores.

• Exemplo: Provar que o loop do Kernel nunca entra em deadlock mesmo sob saturação de backpressure.
• Execução: Através do TLC Model Checker.

3. Lean 4 (Prova de Teoremas)

Usado para garantir a correção de funções puras e fundamentação matemática.

• Exemplo: Prova de que o Hamiltoniano de Ising converge para um estado de energia mínima sob as regras do scheduler.
• Execução: Através do comando lake build no diretório formal.

4. Integração com o Fluxo RSE

Toda RFC que introduz um novo protocolo crítico (ex: um novo portão de segurança ou mecanismo de crédito) deve ser acompanhada de uma especificação formal mínima.

1. Research: Identificar as propriedades de segurança e liveness.
2. Strategy: Escrever o modelo TLA+ ou Lean.
3. Execution: Implementar em Rust e validar contra o modelo.

5. Como rodar as verificações

Utilize o orquestrador canônico:

make verify-formal

Este comando invocará os checkers de TLA+ e os compiladores de Lean 4 configurados no workspace.

6. Veja também

• Qualidade · 4 Esteiras
• Referência · Matemática
• RFC 050 · Dogmas

🗺️ Mapeamento do Workspace

O PAEBIRU é um workspace Cargo extenso com mais de 30 membros. Este guia ajuda você a se localizar e entender a maturidade de cada componente.

1. Estrutura de Diretórios

paebiru/
├── apps/               # Aplicações finais (binários)
├── crates/             # Bounded Contexts e bibliotecas core
│   ├── bindings/       # Bindings para 13 linguagens (FFI)
├── docs/               # Documentação mdBook (esta que você lê)
├── simulations/        # Simulações hardware-in-the-loop (Python)
└── supply-chain/       # Auditorias e travas de dependências

2. Maturidade por Crate (Fase 1)

3. Fluxo de Dependências

Para preservar o Dogma 1 (Isolamento Hexagonal), seguimos uma hierarquia estrita:

1. paebiru-math e paebiru-commons são a base (zero dependências internas).
2. paebiru-kernel depende da base.
3. Bounded Contexts de domínio (biology, economy, learn) dependem do kernel através de traits.
4. paebiru-node orquestra tudo, injetando as implementações concretas.

4. Bindings de Linguagem

Os crates em crates/bindings/ são pontes FFI. Eles não devem conter lógica de domínio, apenas mapeamentos de tipos e chamadas para o core em Rust.

5. Veja também

• Roadmap — Visão temporal da maturidade.
• Qualidade · Dogma 1
• AGENTS.md — Lista técnica completa de crates.

📜 Escrevendo RFCs

Mudanças significativas na arquitetura, protocolos ou economia do PAEBIRU exigem uma RFC (Request for Comments). Este processo garante que as decisões sejam debatidas, documentadas e imutáveis após a ratificação.

1. Quando escrever uma RFC?

• Adição de um novo Bounded Context (crate).
• Mudança em uma interface pública de Port (trait em crates/*/ports/).
• Alteração em protocolos de rede ou formatos de recibo.
• Novas regras de governança ou incentivos econômicos.

2. O Processo (Fluxo Vital)

1. Idea: Discuta a ideia em uma Issue ou Discussion com a tag rfc-proposal.
2. Draft: Solicite um número (ex: RFC 054) e copie o template oficial.
3. Proposed: Abra um PR com o status PROPOSED. O PR deve ficar aberto por pelo menos 14 dias para debate técnico.
4. Standard: Se houver consenso, um mantenedor marca como STANDARD e faz o merge.

3. Template de RFC

Copie de .agents/skills/paebiru-rfc-writer/references/TEMPLATE.md. Seções obrigatórias:

• Resumo: Um parágrafo para leigos.
• Motivação: Por que agora? Qual o custo de não fazer?
• Especificação Técnica: Detalhes granulares (structs, enums, sequências).
• Impacto em BCs: Tabela de quais crates serão alterados.

4. Regras de Ouro

• Numeração Imutável: Uma vez atribuído, o número da RFC nunca muda.
• Supersedes: Se uma RFC nova substitui uma antiga, use o campo supersedes no cabeçalho.
• Foco no Domínio: Evite detalhes de implementação (ex: “usar biblioteca X”) a menos que seja estritamente necessário para o protocolo.

5. Veja também

• Índice de RFCs
• Processo RSE
• Skill paebiru-rfc-writer

✍️ Escrevendo Documentação

A documentação do PAEBIRU é a “memória externa” do organismo. Ela deve ser tão rigorosa quanto o código, seguindo convenções estritas para garantir que seja útil tanto para humanos quanto para agentes de IA.

1. Onde Documentar?

• Documentação Local: Comentários /// (RustDoc) no código. Explique o porquê, não o quê.
• Documentação Transversal: Vive em docs/src/. Use para arquitetura, teoria, guias e runbooks.
• README.md: Cada crate deve ter um README descrevendo apenas seu escopo local.

2. Convenções de Estilo

• Idioma: Português Brasileiro (pt-BR) é o padrão. Termos técnicos canônicos (ex: Maturidade Causal) devem ser preservados.
• Nomenclatura: Arquivos .md usam kebab-case (ex: meu-novo-guia.md).
• Links: Use sempre caminhos relativos (ex: ../architecture/kernel.md). Links absolutos quebram o build.

3. Metadados e Cabeçalhos

Não use YAML frontmatter. O mdBook renderiza YAML como texto visível. Em vez disso, use comentários HTML no topo do arquivo:

<!-- title: Título da Página -->
<!-- audience: novos desenvolvedores -->
<!-- status: DRAFT -->

4. Diagramas (Mermaid)

Prefira diagramas code-first usando Mermaid.js. Eles são fáceis de versionar e eficientes para LLMs processarem.

graph TD;
    A-->B;
    A-->C;

5. Checklist de Documentação

• O arquivo usa kebab-case?
• Os links são todos relativos?
• O metadado está em comentários HTML?
• Usei o Dicionário para termos técnicos?
• Adicionei a nova página ao SUMMARY.md?

6. Veja também

• Dicionário Canônico
• Processo RSE
• AGENTS.md §9 — Documentação

🌐 Internacionalização (i18n)

Embora o português brasileiro (pt-BR) seja o idioma canônico do PAEBIRU, o sistema é projetado para ser global.

1. Prioridade de Idiomas

1. pt-BR: Idioma da documentação de core, RFCs e comentários de código.
2. en-US: Idioma para visibilidade internacional e SDKs.
3. es-ES: Idioma para integração regional na América Latina.

2. Padrões de Tradução

• Termos Canônicos: Termos como Maturidade Causal, Algedonia e Plasmídeo devem ser traduzidos seguindo o glossário oficial para evitar perda de significado técnico.
• Mensagens de Erro: O Kernel emite códigos de erro numéricos, que são traduzidos na camada de API ou CLI para o idioma do usuário.

3. Como Contribuir

Se você deseja traduzir uma página da documentação:

1. Crie uma pasta com o código do idioma (ex: docs/src/en/).
2. Mantenha a estrutura de arquivos idêntica à de docs/src/.
3. Utilize o comando make i18n-check para verificar se há páginas faltando no idioma traduzido.

4. Veja também

• Dicionário Canônico
• Guia · Escrevendo Documentação

❄️ Realidade Fractal

O PAEBIRU segue o Padrão Antropofágico: a mesma estrutura funcional repete-se em múltiplas escalas. Esta auto-similaridade garante que as garantias de segurança e eficiência sejam mantidas do bit à malha global.

1. As 7 Escalas Fractais

O ciclo metabólico (ingerir → metabolizar → excretar) ocorre em:

1. Bit Físico: A unidade mínima de custo termodinâmico.
2. Neurônio LIF: A unidade de processamento neuromórfico (SNN).
3. Função WASM: A unidade lógica dentro de um plasmídeo.
4. Plasmídeo: A unidade de governança e contrato.
5. Nó ABAPORU: A unidade de soberania individual.
6. LocalSyncDomain: O cluster local de alta confiança (Fog).
7. Malha Global: O organismo completo.

2. Por que a fractalidade?

• Escalabilidade: Se um protocolo funciona para coordenar 10 funções em um plasmídeo, ele pode ser adaptado para coordenar 10 nós em um cluster.
• Resiliência: Falhas em uma escala não colapsam o sistema inteiro, pois cada nível mantém sua própria Homeostasia e sensores algedônicos.
• Simplicidade Cognitiva: Desenvolvedores e agentes de IA precisam aprender apenas um padrão fundamental que se aplica a todo o sistema.

3. Invariantes em todas as escalas

• Backpressure: Nenhuma escala pode ser forçada a processar mais do que sua capacidade metabólica permite.
• Recibos: Toda interação gera uma prova de execução/valor.
• Maturidade Causal: O tempo é sempre medido pela progressão de eventos e não por relógios externos.

4. Veja também

• Sistema Celular
• Manifesto · Tese 7
• Referência · Matemática

🧬 Sistema Celular

No PAEBIRU, o nó não é apenas um servidor; ele é uma célula. Esta metáfora biológica dita como os recursos são geridos e como a segurança é enforçada.

1. A Membrana (ZeroTrustPipeline)

Toda célula tem uma membrana que protege seu interior e regula o que entra e sai. No nó, essa membrana é o ZeroTrustPipeline (os 5 portões).

• Seletividade: Apenas pacotes com PoW válido e assinaturas PQC atravessam a membrana.
• Proteção: A membrana é a primeira linha de defesa contra exaustão de recursos (Load Shedding).

flowchart LR
    A[Pacote bruto<br/>UDP/TCP/LoRa] --> P1[Portão 1<br/>eBPF/XDP<br/>load shedder]
    P1 --> P2[Portão 2<br/>PoW BLAKE3<br/>anti-Sybil]
    P2 --> P3[Portão 3<br/>PQC ML-DSA<br/>assinatura]
    P3 --> P4[Portão 4<br/>CDDL contrato<br/>+ ZK-PoL se geo]
    P4 --> P5[Portão 5<br/>MacrophageVM<br/>sandbox + anticorpo]
    P5 --> AC[Aceito · CausalBlock]
    P1 -.drop.-> X[(drop metric)]
    P3 -.drop.-> X
    P5 -.quarentena.-> Q[MacrophageVM]

2. Metabolismo Local

O processamento interno do nó segue um ciclo metabólico:

1. Ingestão: Recebimento de mensagens e estímulos (spikes).
2. Digestão: Processamento via loop GALS e execução de plasmídeos.
3. Excreção: Emissão de Recibos Soberanos e propagação de novos estímulos para a malha.

3. Apoptose e Homeostasia

• Homeostasia: O nó busca manter seu equilíbrio térmico e computacional através de sensores algedônicos.
• Apoptose: Se um componente (plasmídeo ou cache) torna-se disfuncional ou perigoso, o nó realiza a “morte programada” daquele recurso para preservar a integridade da célula.

4. Veja também

• Realidade Fractal
• Dicionário · Algedonia
• Teoria · Arquitetura Cognitiva

🖥️ SO Distribuído

PAEBIRU atua como um Sistema Operacional Distribuído, onde o “hardware” é a malha global de nós heterogêneos.

1. O Kernel como Microkernel

O paebiru-kernel funciona como um microkernel moderno:

• Gerenciamento de Processos: Cada plasmídeo é um processo isolado em uma sandbox WASM.
• IPC (Inter-Process Communication): A troca de mensagens via GossipSub atua como o barramento de sistema (System Bus).
• Drivers: O BC de HAL fornece a interface para o hardware físico.

2. Abstração de Recursos

Diferente de um SO tradicional que gerencia uma CPU local, o PAEBIRU abstrai a capacidade computacional da vizinhança causal:

• Agendamento de Enxame: O scheduler distribui tarefas baseando-se na energia disponível e na latência termodinâmica dos nós vizinhos.
• Memória Causal: O C.A.P.I.B.A. atua como a memória virtual do sistema, onde os dados são endereçados por conteúdo (IPLD) e não por endereço físico.

3. Soberania de Execução

No SO Distribuído do PAEBIRU, não há “usuário root” global. A autoridade é derivada de Recibos Soberanos e consenso de quórum, garantindo que o sistema opere de forma justa e resiliente a falhas de nós individuais.

4. Veja também

• BC Kernel
• BC HAL
• Referência · WASI-PAEBIRU ABI

🦴 Kernel — Espinha Dorsal

O Kernel é o Bounded Context que implementa o loop GALS (Globally Asynchronous, Locally Synchronous) do nó. Ele é a única peça que conhece rede, threads e tempo — o restante dos BCs (biology, economy, capiba, learning, etc.) é puro domínio e se comunica com o Kernel via troca de mensagens.

flowchart LR
    subgraph Adapters [adapters/ · E/S]
        NET[NetworkPort<br/>libp2p]
        TIME[TimePort<br/>tokio::time]
        RES[ResourcePort<br/>sysinfo]
    end
    subgraph Ports [ports/ · traits de I/O]
        P1[NetworkPort]
        P2[TimePort]
        P3[ResourcePort]
    end
    subgraph Types [ports/ · tipos canônicos]
        T1[PeerId]
        T2[MetabolicMessage]
        T3[SystemPressure]
    end
    subgraph Actor [actor/ · loop GALS]
        KA[KernelActor<br/>mpsc receiver]
    end
    subgraph Domain [domain/ · núcleo puro]
        M[Metabolism<br/>peer health +<br/>token bucket]
    end
    NET -.implementa.-> P1
    TIME -.implementa.-> P2
    RES -.implementa.-> P3
    P1 --> KA
    P2 --> KA
    P3 --> KA
    KA -->|handle_message<br/>carrega T1, T2, T3| M
    M -->|MetabolicAction| KA
    KA -->|send_message| P1

Regra de dependência: domain/ nunca importa de actor/, ports/ ou adapters/. A seta vai do actor para o domain — nunca o contrário. Esta é a aplicação do Dogma 1 (Isolamento Hexagonal) ao Kernel.

0.1. O coração metabólico: Token Bucket

O Metabolism é o algoritmo central do GALS: um token bucket canônico com MAX_TOKENS=100 e recarga de 0.1 tokens/ms. Cada mensagem consome 1 token; sem tokens, o ator não bloqueia — ele marca a mensagem como saturada, dispara sinal algedônico e segue. É a implementação concreta do princípio de Backpressure universal.

flowchart LR
    I[Inbound msg] --> R[Refill<br/>tokens = min MAX, t + tokens]
    R --> C{tokens >= 1?}
    C -- não --> S[Saturated<br/>drop + algedonic]
    C -- sim --> H[handle_message]
    H --> T[tokens -= 1]
    T --> A[MetabolicAction<br/>processa e despacha]
    S -.sinal.-> ALG[AlgedonicSensor]
    A --> O[Outbound msg]

1. Anatomia do crate

crates/kernel/src/
├── lib.rs           # exports públicos
├── actor/
│   └── mod.rs       # KernelActor, KernelCommand, KernelHandle
├── domain/
│   └── mod.rs       # Metabolism, MetabolicAction, PeerHealth
├── ports/
│   └── mod.rs       # PeerId, MetabolicMessage, NetworkPort, TimePort, ResourcePort, SystemPressure
└── adapters/
    └── mod.rs       # (vazio por enquanto — implementações concretas virão aqui)

2. Domínio (crates/kernel/src/domain/)

Metabolism

A única estrutura que carrega estado mutável do domínio. Não tem I/O, não tem threads, não tem tokio. É testável em isolamento absoluto com um relógio mockado.

#![allow(unused)]
fn main() {
pub struct Metabolism {
    node_id: PeerId,
    known_peers: HashMap<PeerId, PeerHealth>,
    tokens: f32,            // token bucket (backpressure)
    last_refill_ms: u64,
}
}

Constantes de metabolismo:

Algoritmo:

1. Em cada handle_message, primeiro reabastece o bucket proporcional a now_ms - last_refill_ms.
2. Se tokens < 1.0, retorna MetabolicAction::Saturated (sem consumir).
3. Senão, consome 1 token e processa a mensagem.
4. Para PulseRequest: registra/atualiza o PeerHealth do emissor e agenda PulseResponse.
5. Para PulseResponse: atualiza o health_score do emissor.

MetabolicAction

#![allow(unused)]
fn main() {
pub enum MetabolicAction {
    SendResponse { target: PeerId, msg: MetabolicMessage },
    UpdateInternalState,
    Saturated,   // backpressure sinalizou overload
    None,
}
}

Invariante: Metabolism::handle_message é puro — dado o mesmo (sender, msg, now_ms) e o mesmo estado inicial, produz a mesma MetabolicAction. Isso é verificável por proptest.

PeerHealth

#![allow(unused)]
fn main() {
pub struct PeerHealth {
    pub last_seen_ms: u64,
    pub health_score: f32,
}
}

health_score ∈ [0.0, 1.0]; valores perto de 0 indicam peer degradado e disparam o sensor algedônico (futuro: roteamento adaptativo).

3. Portas (crates/kernel/src/ports/)

Definem tudo que o domínio vê do mundo, sem saber quem implementa.

PeerId

#![allow(unused)]
fn main() {
pub struct PeerId([u8; 32]);
}

32 bytes opacos. Display mostra os primeiros 8 bytes em hex (para logs).

MetabolicMessage

#![allow(unused)]
fn main() {
pub enum MetabolicMessage {
    PulseRequest  { timestamp: u64 },
    PulseResponse { timestamp: u64, health: f32 },
}
}

Por enquanto, apenas duas variantes — hello da malha. O conjunto crescerá conforme os outros BCs (biology, economy) enviarem mensagens de domínio. Cada nova variante é uma mudança compatível para trás (apenas adição), preservável por versionamento de envelope.

NetworkPort (assíncrono)

#![allow(unused)]
fn main() {
#[async_trait]
pub trait NetworkPort: Send + Sync {
    /// Envia uma mensagem metabólica para um peer específico.
    async fn send_message(&self, target: PeerId, msg: MetabolicMessage) -> Result<(), &'static str>;

    /// Broadcast de uma mensagem para todos os peers conhecidos.
    async fn broadcast(&self, msg: MetabolicMessage) -> Result<(), &'static str>;
}
}

Implementação concreta atual: apps/node/src/network.rs (libp2p).

TimePort (síncrono)

#![allow(unused)]
fn main() {
pub trait TimePort: Send + Sync {
    fn now_ms(&self) -> u64;
}
}

Síncrono de propósito: facilita proptest (testes determinísticos bancam o tempo com um contador). Não usar Instant::now() diretamente no domínio.

ResourcePort (síncrono)

#![allow(unused)]
fn main() {
pub trait ResourcePort: Send + Sync {
    fn get_current_pressure(&self) -> SystemPressure;
}
}

SystemPressure é o que alimenta o sensor algedônico do nó (local, sem supervisor global).

#![allow(unused)]
fn main() {
pub struct SystemPressure {
    pub cpu_usage: f32,     // [0.0, 1.0]
    pub memory_usage: f32,  // [0.0, 1.0]
    pub disk_usage: f32,    // [0.0, 1.0]
}
}

4. Ator (crates/kernel/src/actor/)

KernelCommand

Mensagens que o Node (camada de fora) envia para o ator:

#![allow(unused)]
fn main() {
pub enum KernelCommand {
    IncomingMessage { sender: PeerId, message: MetabolicMessage },
    TriggerPulse,
    Shutdown,
}
}

KernelActor

#![allow(unused)]
fn main() {
pub struct KernelActor {
    metabolism: Metabolism,
    network_port: Arc<dyn NetworkPort>,
    time_port:   Arc<dyn TimePort>,
    resource_port: Arc<dyn ResourcePort>,
    receiver:    mpsc::Receiver<KernelCommand>,
}
}

O loop principal:

#![allow(unused)]
fn main() {
pub async fn run(mut self) {
    while let Some(command) = self.receiver.recv().await {
        match command {
            KernelCommand::IncomingMessage { sender, message } => {
                let now = self.time_port.now_ms();
                let action = self.metabolism.handle_message(sender, message, now);
                self.execute_action(action).await;
            }
            KernelCommand::TriggerPulse => { /* pulso metabólico */ }
            KernelCommand::Shutdown => break,
        }
    }
}
}

Regra do Dogma 2 (GALS): o loop do ator nunca bloqueia em I/O. Toda chamada externa é async e awaitada; o mpsc::Receiver é o único ponto de suspensão.

KernelHandle

pub use em lib.rs — é a handle que o Node usa para enviar comandos ao ator:

#![allow(unused)]
fn main() {
pub struct KernelHandle {
    sender: mpsc::Sender<KernelCommand>,
}
}

#![allow(unused)]
fn main() {
impl KernelHandle {
    pub async fn incoming(&self, sender: PeerId, msg: MetabolicMessage) -> Result<(), ...>;
    pub async fn trigger_pulse(&self) -> Result<(), ...>;
    pub async fn shutdown(&self) -> Result<(), ...>;
}
}

5. Adaptadores (crates/kernel/src/adapters/)

Por enquanto apenas:

#![allow(unused)]
fn main() {
pub mod networking {}
}

A implementação concreta está em apps/node/src/network.rs — uma decisão consciente: o Kernel é uma biblioteca no_std-friendly que não inclui libp2p. A integração com a rede física vive no Node (binário). Em fases futuras, a tendência é mover implementações para cá para reuso em outros front-ends (CLI, playground, simulator).

6. Fluxo end-to-end (exemplo)

Uma mensagem chegando do libp2p:

sequenceDiagram
    participant N as Network (libp2p)
    participant H as KernelHandle
    participant A as KernelActor (loop)
    participant D as Metabolism (domain)
    participant R as ResourcePort
    N->>H: incoming(sender, PulseRequest)
    H->>A: mpsc::send(IncomingMessage)
    A->>R: get_current_pressure()
    A->>D: handle_message(sender, msg, now)
    D-->>A: MetabolicAction::SendResponse
    A->>N: network_port.send_message(...)
    N-->>Sender: PulseResponse

Garantia: todo o caminho passa por um único thread (o loop do ator). Não há Mutex no Metabolism — a imutabilidade estrutural do actor é o “lock”.

Transporte e descoberta do pulso

A integração libp2p concreta vive em apps/node/src/network.rs. O pulso trafega em gossipsub (tópico paebiru-metabolism), que é o canal de publicação efêmero e ponto-a-ponto. Os peers que assinam este tópico são descobertos por duas camadas complementares:

• mDNS (LAN) — plug-and-play local, sem configuração.
• Kademlia DHT (global) — anel de peers roteáveis, alimentado por PAEBIRU_BOOTNODES. O gate F1 do Roadmap (“dois nós trocam pulse ponta-a-ponta via libp2p Kademlia”) é satisfeito pela combinação Kademlia-para-descoberta + gossipsub-para-transporte; o pulso não é armazenado como Kademlia Record — ele é efêmero por design (ver Pulse no Dicionário).

O Dogma 1 (Hexagonal) é preservado: este BC não conhece libp2p, mDNS ou Kademlia. Toda a complexidade de transporte vive no Node (apps/node), satisfazendo o NetworkPort que o KernelActor consome. O Dogma 3 (no_std) também permanece intacto — o paebiru-kernel continua compilável para riscv32imc-unknown-none-elf e thumbv7em-none-eabihf.

7. Como testar

Cobertura-alvo: ≥ 90 % (enforçada por make coverage).

8. O que não é Kernel

• Persistência → capiba.md (outro BC).
• Aprendizado / modelos → BC learning.
• Crédito / Loteria Joule → BC economy.
• Agentes BDI / SNN → BC biology.
• Definição de plasmídeos → BC plasmids.

Se a mudança que você quer fazer não é loop de ator, porta ou adaptação de E/S, provavelmente é outro BC.

9. Veja também

• Dicionário · GALS
• Dicionário · Maturidade Causal
• Dicionário · Sensor algedônico
• Capiba · Memória persistente (o BC vizinho que consome receipts do Kernel)
• Quatro Dogmas Inquebráveis
• Glossário da skill paebiru-architect

🌿 Biologia — O Organismo

O Bounded Context de Biologia implementa a camada cognitiva e metabólica do PAEBIRU. Enquanto o kernel cuida da sobrevivência mecânica (rede, mensagens), a biologia cuida da sobrevivência adaptativa: como o nó percebe o ambiente, como toma decisões (ABAPORU) e como economiza energia via redes neuromórficas (SNN).

flowchart TB
    subgraph Inputs [Percepção]
        S[Sensores Algedônicos]
        M[Mensagens da Malha]
    end
    subgraph Cognition [Cognição · ABAPORU]
        B[Crenças · Beliefs]
        D[Desejos · Desires]
        I[Intenções · Intentions]
    end
    subgraph Execution [Metabolismo]
        SNN[SNN · Spiking Neural Network]
        BC[Backpressure Causal]
    end
    Inputs --> B
    B --> D
    D --> I
    I --> Execution
    Execution -->|Feedback| S

1. ABAPORU — Agente BDI

O ABAPORU é o agente autônomo que reside em cada nó. Ele segue o modelo BDI (Belief-Desire-Intention):

• Beliefs (Crenças): Representam o que o nó sabe sobre o mundo (estado dos peers, maturidade causal, topologia da malha).
• Desires (Desejos): Objetivos de alto nível (manter latência baixa, maximizar créditos, economizar bateria).
• Intentions (Intenções): Planos concretos de ação (re-rotear pacotes, iniciar round de FedAvg, entrar em hibernação).

2. Redes Neuromórficas (SNN)

Para processamento de ultra-baixa energia, especialmente em MuleNodes, a biologia utiliza Spiking Neural Networks (SNN) com neurônios LIF (Leaky Integrate-and-Fire).

• Sparsity: A informação é transmitida via spikes (pulsos) no tempo. Se não há atividade, não há consumo de CPU.
• Hardware-Aware: A rede ajusta sua densidade (sparsity) com base no sinal de dor (algedonia) do hardware.

3. Metabolismo e Homeostasia

O nó é tratado como uma célula metabólica. O sistema busca manter a homeostasia através de:

• Sensores Algedônicos: Monitoram temperatura, CPU e memória. Se o “prazer” cai abaixo do limiar, o nó entra em modo defensivo.
• Veto Algedônico: Um mecanismo de segurança onde o hardware pode interromper a governança lógica para evitar dano físico (ex: superaquecimento).
• Backpressure: O metabolismo do nó dita o ritmo de processamento. O MetabolicAction do Kernel é o sinal de “fome” ou “saciedade” do sistema.

4. Invariantes do Domínio

1. Soberania Decisória: O ABAPORU local sempre tem a palavra final sobre o uso de seus recursos.
2. Prioridade Termodinâmica: A sobrevivência física do nó (homeostasia) precede qualquer objetivo da malha.
3. Maturidade Causal: Decisões de aprendizado e evolução seguem o tempo de Langevin, não o cronológico.

5. Veja também

• Dicionário · ABAPORU
• Dicionário · Algedonia
• Teoria · Arquitetura Cognitiva
• RFC 032 · Plasmídeos

💸 Economia — O Tecido

O Bounded Context de Economia é o tecido que conecta os nós através de incentivos materiais e reciprocidade. No PAEBIRU, a economia não é baseada em moedas fiduciárias centralizadas, mas em recursos termodinâmicos reais (energia, computação, banda) e crédito mútuo.

flowchart LR
    subgraph DRE [Distributed Receipt Engine]
        R[Recibo Soberano]
    end
    subgraph Engine [Barter & Ledger]
        B[Barter Engine]
        LL[Landauer Ledger]
        MC[Crédito Mútuo]
    end
    subgraph Rewards [Incentivos]
        LJ[Loteria Joule]
        DAO[Governança DAO]
    end
    R --> B
    B --> MC
    MC --> LL
    LL --> LJ
    LJ --> DAO

1. DRE — Distributed Receipt Engine

Toda interação econômica no PAEBIRU gera um Recibo Soberano.

• Imutabilidade: Assinado via ML-DSA (Portão 3).
• Auditabilidade: Persistido no C.A.P.I.B.A. para verificação futura.
• Prova de Valor: O recibo contém o custo energético da operação em micro-joules (µJ).

2. Barter Engine e Crédito Mútuo

O PAEBIRU utiliza um sistema de permuta (barter) e crédito mútuo de soma zero:

• Bilateralidade: Dois nós podem trocar recursos diretamente (ex: banda por armazenamento).
• Multilateralidade: A malha realiza a compensação de saldos entre múltiplos nós periodicamente.
• Soma Zero: Não existe criação de “moeda” do nada; o crédito de um nó é o débito de outro, mantendo o equilíbrio do sistema.

3. Loteria Joule

A Loteria Joule é o mecanismo de recompensa para nós que contribuem com poder computacional real para a malha:

• Input: Provas de trabalho e contribuições de aprendizado federado.
• Output: Distribuição de direitos de prioridade e créditos na malha.
• Termodinâmica: Baseada no custo de Landauer; quem economiza energia para a malha é recompensado.

4. Landauer Ledger

O livro-razão fundamental do sistema. Ele registra o débito termodinâmico de cada operação.

• Cada portão do ZeroTrustPipeline tem um custo fixo em µJ.
• O ledger garante que a computação não seja tratada como gratuita, prevenindo abusos e ataques de negação de serviço econômico.

5. Invariantes do Domínio

1. Soma Zero: O balanço global de créditos e débitos deve ser sempre zero.
2. Materialidade: Todo crédito deve ser lastreado em contribuição real de recurso (energia/computação/dado).
3. Privacidade: As transações preservam a soberania do nó; detalhes granulares são revelados apenas sob quorum.

6. Veja também

• Dicionário · DRE
• Dicionário · LandauerLedger
• Dicionário · Loteria Joule
• Teoria · Fundamentos Termodinâmicos

🌊 C.A.P.I.B.A. — Memória Persistente Causal

Causal, Asynchronous, Persistent, Immutable Block Architecture — a memória de longo prazo do PAEBIRU. Onde o kernel cuida da mensagem em trânsito, o capiba cuida da mensagem em repouso: como ela se torna dado, como o dado se torna conhecimento, e como o conhecimento se preserva no tempo causal.

flowchart LR
    subgraph Hot [Hot path · µs–ms]
        N[1. Nascente<br/>Ring Buffer / RAM]
    end
    subgraph Warm [Warm path · ms–s]
        C[2. Correnteza<br/>MmapStore / WAL<br/>Prolly Trees]
        M[3. Manguezal<br/>Arrow in-memory<br/>+ Zero-Trust filter]
    end
    subgraph Cold [Cold path · s–min]
        O[4. Oceano<br/>Iceberg + IPLD CIDs]
    end
    subgraph Volatile [Volatile · min–h]
        Ch[5. Chuva<br/>Compute-over-data<br/>→ Plasmídeo WASM]
    end
    N -->|Langevin Tick| C
    C -->|Pororoca Causal<br/>sync P2P| M
    M -->|Transmutação Analítica<br/>Parquet| O
    O -->|Compute-over-Data| Ch
    Ch -->|Precipitação<br/>Evolutiva| N

Princípio-guia: C.A.P.I.B.A. não é “um banco de dados” — é um ecossistema metabólico de dados com 5 estágios análogos ao ciclo hidrológico. Cada estágio tem temperatura termodinâmica, formato de representação e função diferentes. Nada “vira storage” por inércia; cada bloco é causalmente endereçado e tem uma vida útil declarada pelo seu MUS (Minimum Useful Survival).

1. Fronteira do BC

Membranas existem por uma razão: se o problema não é de dados, é de outro BC. Devolva o ticket; não estique a membrana.

2. Os 5 estágios

Cada estágio é um trade-off explícito entre latência, consistência e custo termodinâmico. A escolha do estágio é arquitetural, não operacional — não se move dado entre estágios por conveniência.

2.1 Nascente (Hot) — capiba::ring

• Função: captura de evento no momento de criação.
• Representação: ring buffer lock-free em RAM; ~µs de latência.
• Transição para o próximo: Langevin Tick — quando o bloco resfria (i.e., outros nós da sua vizinhança causal já o viram), é despejado no WAL.
• Consistência: estritamente local; sem replicação.
• Limite de tamanho: PAEBIRU_NASCENTE_RING_BYTES (default 256 MB).
• Anti-padrão: usar Nascente como fila durável. Não é.

2.2 Correnteza (Warm) — capiba::mmap::wal + capiba::prolly

• Função: buffer causal, replicável entre nós da LocalSyncDomain.
• Representação: MmapStore (WAL posix) + Prolly Tree indexada por DVV.
• Transição para o próximo: Pororoca Causal — batched sync P2P com delta-sync via Bloom filter.
• Consistência: causal (não cronológica).
• Filtros: StigmergicImmuneSystem — pacotes que violam invariante causal são desviados para o Manguezal como “lama tóxica”.
• MuleNodes (LoRa, ATmega): usam Pororoca com janelas Langevin estendidas, eventualmente consistente.

2.3 Manguezal (Cool) — capiba::arrow

• Função: análise intermediária + quarentena Zero-Trust.
• Representação: Apache Arrow in-memory; transações vetoriais columnares.
• Transição para o próximo: Transmutação Analítica — quando o bloco passa no filtro Zero-Trust (CDDL + validação semântica + ZK-PoL se houver geolocalização), é despejado em Parquet e preparado para o Oceano.
• Consistência: forte eventual; semântica “read-your-writes” no mesmo nó.
• Quarentena: blocos suspeitos → MacrophageVM (ver Tópicos em formalização) para síntese de anticorpos. Nunca se executa o conteúdo de um bloco em Manguezal sem passar pelo Portão 5 (CDDL).

2.4 Oceano (Cold) — capiba::iceberg + capiba::ipfs

• Função: cold storage soberano, auditável, replicado via erasure coding entre nós da Confederation Tier.
• Representação: Apache Iceberg (snapshot lineage) + IPLD CID v1 com multicodec + multihash (BLAKE3).
• Transição para o próximo: Erasure Coding + Sovereignty Gate — antes de descer, dados são auditados. Sovereignty Gate verifica soberania (não violação de jurisdição, não dado pessoal sem máscara, etc.).
• Consistência: eventual; snapshots imutáveis.
• Migração irreversível: uma vez no Oceano, o dado é tratado como fato histórico. Mudanças exigem novo bloco causal.

2.5 Chuva (Volatile) — capiba::compute

• Função: compute-over-data. Gradientes para treino federado; pesos viram plasmídeo (regra distribuída).
• Representação: trainer federado (FLAIR/Ising) que consome Iceberg manifest e emite WeightDelta.
• Transição para o próximo: Precipitação Evolutiva — WeightDelta vira plasmídeo WASM (ver Tópicos em formalização) com versão própria.
• Idempotência: aplicar o mesmo plasmídeo duas vezes = aplicar uma única vez. Chuva é convergente.
• Anti-padrão: Chuva que move o Oceano. Compute vai até o storage; storage nunca vai até o compute.

3. Modelo de dados canônico

Invariante fundamental: todo bloco carrega seu DVV. Nenhum bloco é persistido sem DVV válido (verificável contra qualquer peer da vizinhança causal).

4. Princípios operacionais (vinculantes)

1. Tempo causal, não cronológico. Ordenação por DVV. Instant::now() e timestamps de wall-clock nunca são fonte de verdade para ordenação.
2. Content addressing. Endereço é o par (BLAKE3(conteúdo), DVV). Mesmo conteúdo em maturidades diferentes = CIDs diferentes.
3. Apoptose saudável. MUS define a maturidade abaixo da qual o bloco evapora. Não é “limpeza” — é metabolismo.
4. Sovereignty Gate. Antes de Oceano, audit (CDDL + semântica + ZK-PoL se houver geolocalização).
5. Compute-over-data > move-data. Compute vai até o storage.
6. Quarentena imunológica. Manguezal é filtro Zero-Trust; lama tóxica → MacrophageVM.
7. Sincronização MuleNode. Pororoca Causal: batched, eventual, com _receipts_ imutáveis.
8. Backpressure de I/O. Profundidade finita no WAL; produtor adapta-se ao consumidor (jamais buffer infinito).

Violação de qualquer um destes princípios é regressão automática.

5. Tipos de operação

6. Tópicos a formalizar (vinculantes a médio prazo)

Estes tópicos precisam virar RFC ratificada antes de mudanças no contrato público do C.A.P.I.B.A.:

• Definição e motivação do C.A.P.I.B.A.; Prolly Trees
• CIDs IPLD + content addressing BLAKE3
• Apoptose — esquecimento saudável (MUS)
• Iceberg catalog no Oceano
• Landauer Gate — custo termodinâmico da retenção
• Fail-stop em 7 escalas (também C.A.P.I.B.A.)

A lista canônica e o estado de cada tópico vivem em RFCs em construção. Mudanças em qualquer um destes pontos exigem RFC ratificada (ver processo).

7. Relação com outros BCs

flowchart LR
    K[kernel<br/>mensagem em trânsito] -->|receipt| CAP[capiba<br/>mensagem em repouso]
    B[biology<br/>ABAPORU] -->|causal events| CAP
    E[economy<br/>Loteria Joule] -->|WeightDelta| CAP
    L[learn<br/>FedAvg] -->|gradient sync| CAP
    Z[zk<br/>ZK-PoL proofs] -->|sovereignty proofs| CAP
    CAP -->|compute-over-data| L
    CAP -->|stored receipts| E
    CAP -->|snapshots| AP[api<br/>query federada]

• kernel ↔ capiba: todo receipt soberano é persistido como CausalBlock; toda leitura de receipt é via DVV (não por timestamp).
• biology ↔ capiba: eventos de ABAPORU (crença, desejo, intenção) viram blocos causais; memória de longo prazo do agente = Nascente + Correnteza.
• learn ↔ capiba: trainer federado (Chuva) consome Iceberg (Oceano) e emite plasmídeo (precipitação).
• economy ↔ capiba: o DRE (Data Refinery Engine) usa C.A.P.I.B.A. como insumo canônico para o LandauerLedger.
• zk ↔ capiba: provas de ZK-PoL entram no Sovereignty Gate antes da migração para Oceano.

8. Quando não é C.A.P.I.B.A.

• “Mensagem demora para chegar” → kernel, não dados.
• “Modelo não converge” → learn, não dados.
• “Quem pode escrever X?” → economy + DAO, não dados.
• “Como assino bloco Y?” → kernel (segurança), não dados.

9. Padrões de mudança

Adicionar coluna a um schema Iceberg

1. Migration no DRE (capiba::dre::migrations).
2. Atualizar MusThreshold se a coluna afeta retenção.
3. Atualizar este documento.
4. Teste de round-trip causal (escreve → lê em DVV maior → compara).
5. make test + fuzzing de serialização Iceberg.

Adicionar política de apoptose (MUS)

1. Invariante formal em TLA+ (capiba/formal/).
2. Implementação em capiba::domain::apoptosis.
3. Teste property-based com maturidades aleatórias.
4. Verificar que a Landauer Gate não viola $k_B \cdot T \cdot \ln 2$.
5. Métrica Prometheus: paebiru_capiba_apoptosis_total.

Criar novo MuleNode adapter (CAN bus, Modbus)

1. Implementar capiba::ports::MuleTransport.
2. Adapter em capiba::adapters::mule::<tecnologia>.
3. Garantir no_std compatível.
4. cargo check --target thumbv7em-none-eabihf.
5. Atualizar este documento (tabela de estágios, se aplicável).

10. Checklist para mudanças em capiba

• A mudança é no C.A.P.I.B.A. e não em outro BC?
• Timestamps de wall-clock não são usados para ordenação (DVV)?
• Content addressing (BLAKE3/IPLD) é usado, não path?
• MUS/Apoptose foram considerados?
• Se toca rede/cripto, paebiru-security foi consultado?
• Se toca ML/inferência, paebiru-ai foi consultado?
• Testes property-based para invariantes causais?
• cargo test -p paebiru-capiba + --target thumbv7em-none-eabihf se aplicável?
• Documentação (este arquivo) atualizada?

Veja também

• Dicionário canônico · C.A.P.I.B.A.
• Skill paebiru-data — fonte operacional
• Math foundations · DVV
• Math foundations · Landauer
• Maturidade Causal · fila M/M/1
• Tópicos a formalizar — versões formais em construção

🌀 Entropia

O Bounded Context de Entropia é o fundamento termodinâmico do PAEBIRU. Ele gerencia o tempo, o custo da informação e o equilíbrio energético do sistema, transformando leis da física em regras de protocolo.

1. Landauer Ledger

Baseado no Princípio de Landauer, que estabelece o custo energético mínimo para apagar um bit de informação ($k_B T \ln 2$):

• Custo de Esquecimento: Toda vez que o sistema descarta dados (limpeza de cache, expiração de logs), há um custo computacional e energético associado.
• Escassez Real: A computação no PAEBIRU não é tratada como infinita; ela é limitada pela capacidade do nó de dissipar calor e gerir sua entropia.

2. Langevin Ticks e Tempo Termodinâmico

O tempo no PAEBIRU não segue apenas o relógio de silício, mas a Dinâmica de Langevin:

• Δt ∝ ΔS / γ: O tempo avança proporcionalmente à variação de entropia ($\Delta S$) e inversamente ao atrito termodinâmico ($\gamma$).
• Dança Politemporal: Diferentes partes da malha podem operar em ritmos diferentes (escalas de tempo) dependendo de sua atividade metabólica.

3. Sensor Algedônico e Homeostasia

A entropia monitora a “desordem” do sistema através de feedback sensorial:

• Dor (Pain): Aumento de entropia não controlada (vazamento de memória, loops infinitos) dispara sinais algedônicos de dor.
• Prazer (Pleasure): Estados de baixa entropia e alta eficiência geram sinais de prazer, incentivando o nó a manter aquele estado.

4. Invariantes do Domínio

1. Conservação de Energia: O custo de processamento deve ser sempre contabilizado no LandauerLedger.
2. Irreversibilidade: Operações que modificam o estado global são tratadas como processos termodinâmicos irreversíveis.
3. Equilíbrio Local: Cada nó busca o seu próprio estado de mínima energia através de otimização estocástica (Langevin SGD).

5. Veja também

• Dicionário · Langevin Ticks
• Dicionário · LandauerLedger
• Teoria · Fundamentos Termodinâmicos
• Referência · Matemática

🧠 Aprendizado

O Bounded Context de Aprendizado implementa a inteligência distribuída do PAEBIRU através de Aprendizado Federado (Federated Learning). Aqui, o conhecimento é construído de forma colaborativa sem que os dados brutos jamais saiam de seus nós de origem.

1. Arquitetura Federada

O PAEBIRU utiliza um modelo de federação descentralizada:

• FedAvg (Federated Averaging): Algoritmo padrão para agregação de pesos de modelos.
• Deltas de Peso: Os nós treinam localmente e enviam apenas a diferença (delta) dos pesos, reduzindo drasticamente o uso de banda.
• Agregação Bizantina: Mecanismos como Krum e FoolsGold são usados para detectar e descartar contribuições maliciosas ou ruidosas.

2. Split-DNN e Privacidade

Para modelos complexos que não cabem inteiramente em um MuleNode, utilizamos Split-DNN:

• Fatiamento: A rede neural é dividida. O nó de borda executa as primeiras camadas (extração de features) e um nó de fog/cloud executa as camadas finais.
• Differential Privacy: Adição de ruído controlado aos gradientes para garantir que informações sensíveis não possam ser reconstruídas.

3. Hardware-Aware Learning (FLAIR)

O aprendizado é sensível ao estado físico do nó através do framework FLAIR:

• Pruning Adaptativo: Se um nó está com bateria baixa ou alta temperatura (Algedonia), ele reduz a densidade do modelo (pruning) para economizar energia.
• Quantização Dinâmica: Alternância entre precisão total (FP32) e quantização agressiva (INT4/INT8) com base na disponibilidade de recursos.

4. Integração com Plasmídeos

O resultado de um round de aprendizado federado é frequentemente encapsulado em um Plasmídeo:

1. O agregador consolida os pesos.
2. Os novos pesos são injetados em um template de plasmídeo.
3. O plasmídeo é assinado via FROST (assinaturas distribuídas).
4. A nova “inteligência” é propagada pela malha.

5. Invariantes do Domínio

1. Soberania do Dado: Dados brutos nunca são transmitidos.
2. Resiliência Bizantina: O sistema deve convergir mesmo com uma porcentagem de nós adversariais.
3. Maturidade Causal: Rounds de aprendizado são ordenados via DVV para evitar ataques de replay ou confusão temporal.

6. Veja também

• Dicionário · FedAvg
• Dicionário · Agregação Bizantina
• Teoria · Arquitetura Cognitiva
• Skill paebiru-ai

🔌 API

O Bounded Context de API é a membrana de comunicação externa do nó PAEBIRU. Ele expõe as capacidades do sistema para o mundo exterior através de interfaces REST e gRPC, garantindo observabilidade e auditabilidade através de Recibos Soberanos.

1. Recibos Soberanos (DRE)

A principal saída da API não são apenas dados, mas Recibos Soberanos gerados pelo Distributed Receipt Engine (DRE):

• Verificabilidade: Cada resposta da API é acompanhada por uma assinatura criptográfica pós-quântica (ML-DSA).
• Prova de Execução: O recibo serve como prova de que uma computação ou transação ocorreu em um determinado nó sob certas condições.
• Monetização: Recibos podem ser usados para liquidação no BC de Economia.

2. Interface HTTP (Axum)

A implementação padrão utiliza o framework Axum para oferecer uma interface de alto desempenho:

• Endpoints de Saúde: /healthz e /readiness para orquestração.
• Métricas: /metrics no formato Prometheus para monitoramento de metabolismo.
• Comandos: Endpoints para injeção de plasmídeos e consulta de estado causal.

3. Observabilidade e Tracing

O PAEBIRU segue o padrão OpenTelemetry (OTel) para garantir que cada mensagem possa ser rastreada através da malha:

• Distributed Tracing: Uso de tracing e opentelemetry para correlacionar eventos entre nós.
• Logs Estruturados: Logs em formato JSON para fácil ingestão por sistemas como Grafana Loki.
• Sensores de Stress: A API expõe o estado dos sensores algedônicos para sistemas de monitoramento externos.

4. Invariantes do Domínio

1. Segurança por Default: Nenhum endpoint de mutação de estado é exposto sem autenticação mútua (mTLS) ou prova de identidade soberana.
2. Backpressure de API: Se o nó estiver saturado (metabolismo alto), a API retorna 429 Too Many Requests com base nos tokens do Kernel.
3. Idempotência: Operações de mutação devem ser idempotentes através de identificadores únicos no cabeçalho da API.

5. Veja também

• Dicionário · DRE
• Dicionário · ZeroTrustPipeline
• Arquitetura · Bounded Contexts
• Referência · CLI do Forge

🌉 Bridges Web3

O Bounded Context de Bridges é a ponte que conecta o PAEBIRU a outros ecossistemas descentralizados. Ele permite que a malha PAEBIRU consuma oráculos, armazene dados em redes de preservação e interaja com identidades de IoT externas.

1. Filecoin / IPFS (Armazenamento)

Para dados que excedem a capacidade de retenção local (Oceano) ou que exigem persistência global de longo prazo:

• IPLD: O PAEBIRU utiliza CIDs IPLD nativamente para endereçamento de conteúdo.
• Filecoin Deals: A ponte automatiza a criação de storage deals para persistir snapshots críticos da malha em provedores Filecoin.

2. Chainlink (Oráculos)

Para injetar dados do mundo real ou de outras blockchains de forma confiável:

• Price Feeds: Consumo de preços de ativos para a Barter Engine.
• VRF (Verifiable Random Function): Uso de aleatoriedade auditável para a seleção de quóruns e sorteios na Loteria Joule.
• Functions: Execução de scripts externos que alimentam as crenças (Beliefs) do ABAPORU.

3. IoTeX (Identidade IoT)

Para integração com hardware soberano e dispositivos de borda já existentes:

• W3bstream: Integração com a camada de computação off-chain da IoTeX para prova de eventos físicos.
• DID: Mapeamento de identidades IoTeX para PeerIDs do PAEBIRU, permitindo que dispositivos IoTeX participem da malha como MuleNodes.

4. Invariantes do Domínio

1. Abstração de Protocolo: O Kernel não sabe que está falando com a Ethereum ou Filecoin; ele interage com BridgePorts genéricos.
2. Minimização de Confiança: Toda ponte deve incluir verificação local de provas (ex: proofs de inclusão Merkle) sempre que possível.
3. Assincronia Estrita: Interações com redes externas lentas nunca devem bloquear o metabolismo local do nó.

5. Veja também

• Dicionário · C.A.P.I.B.A.
• Arquitetura · Bounded Contexts
• RFC 025 · Camada 9

📦 Commons

O Bounded Context de Commons contém os tipos fundamentais, macros e utilitários que são compartilhados por todos os outros crates do workspace. Ele é a “gramática” básica do PAEBIRU.

1. Tipos Fundamentais

O Commons define as estruturas que atravessam as membranas de todos os BCs:

• Identificadores: PeerId, PlasmidId, ReceiptId.
• Envelopes de Mensagem: Estruturas genéricas de transporte que garantem serialização e deserialização consistente (FlatBuffers/Serde).
• Resultados e Erros: Tipos de erro canônicos que facilitam o tratamento de falhas em cascata.

2. Macros e Utilitários

Para manter o código DRY (Don’t Repeat Yourself) sem violar o isolamento:

• Logging: Wrappers sobre tracing que injetam contexto metabólico (Langevin Ticks) em todos os logs.
• Profiling: Ferramentas de medição de performance no_std compatíveis.
• Validation: Macros para validação de invariantes em tempo de compilação e execução.

3. Invariantes do Domínio

1. Minimalismo: O Commons deve ter o mínimo de dependências possível.
2. Estabilidade: Por ser a base do grafo de dependências, mudanças no Commons devem ser raras e extremamente bem testadas.
3. Pureza: O Commons não deve conter lógica de negócio específica de nenhum outro BC.

4. Por que commons e não utils?

No PAEBIRU, evitamos o termo utils para desencorajar o acúmulo de código sem propósito claro. O Commons representa recursos compartilhados que são propriedade coletiva de todos os contextos, seguindo a metáfora de bens comuns.

5. Veja também

• Qualidade · 4 Dogmas
• Arquitetura · Bounded Contexts
• Dicionário

⚙️ HAL Embarcado

O Bounded Context de HAL (Hardware Abstraction Layer) é o que permite ao PAEBIRU rodar em dispositivos com recursos extremamente limitados, como microcontroladores de 8, 16 e 32 bits. Ele segue o Dogma 3 (no_std First).

1. Suporte a Hardware

O PAEBIRU HAL é projetado para ser agnóstico, suportando diversas arquiteturas através de traits do embedded-hal.

2. Primitivas no_std

Para garantir a execução em ambientes sem sistema operacional (bare-metal), o HAL utiliza:

• Gerenciamento de Memória: Uso extensivo de heapless para coleções de tamanho fixo em stack, evitando fragmentação de heap.
• Criptografia Leve: Implementações otimizadas de BLAKE3 e assinaturas PQC que cabem em menos de 100 KB de ROM.
• Concorrência: Baseada em interrupções e loops cooperativos (RTIC ou similar).

3. Periféricos e MuleNodes

Os MuleNodes são nós de borda que utilizam o HAL para se comunicar com o mundo físico:

• Sensores: GPIO, ADC, I²C, SPI para captura de dados metabólicos.
• Comunicação: Drivers para LoRa (SX1262), CAN bus e Modbus RTU.
• Energy Harvesting: Lógica de gerenciamento de energia para nós alimentados por painéis solares ou vibração.

4. Invariantes do Domínio

1. Eficiência Estrita: Cada ciclo de clock e byte de RAM deve ser justificado (Dogma 3).
2. Abstração Transparente: O domínio do HAL expõe traits genéricos para que o kernel e biology possam rodar o mesmo código lógico em x86 ou RISC-V.
3. Resiliência de Boot: O HAL deve garantir um estado seguro de boot mesmo em condições de baixa voltagem.

5. Veja também

• Dicionário · MuleNode
• Setup · Alvos Embarcados
• Qualidade · Dogma 3
• Operadores · Flashing Embarcado

🧬 Plasmídeos

O Bounded Context de Plasmídeos é a fábrica de código de contrato do PAEBIRU. Cada plasmídeo é um pequeno programa auto-contido, escrito em uma DSL de alto nível (TOML/HCL), compilado para WebAssembly e executado dentro de uma membrana do BC C.A.P.I.B.A. — o plasmídeo é, ao mesmo tempo, código e dado: ele migra entre nós como um CausalBlock imutável.

⚠️ Stub documental. O crate paebiru-plasmids ainda não está implementado no workspace (somente o kernel está materializado em crates/). Este arquivo existe para (a) desbloquear o build do mdBook em modo strict — o SUMMARY.md precisa de um capítulo apontando para o BC Plasmídeos — e (b) servir de contrato canônico para a primeira implementação. Ver ROADMAP §Fase 2 e tópico em formalização.

1. Fronteira do BC

2. Estado atual e roadmap

• Pré-Fase 2 — projeto apenas arquitetado.
• A sintaxe-alvo está descrita em Referência · DSL de Plasmídeos.
• A interface binária está descrita em Referência · WASI-PAEBIRU ABI.
• O compilador será escrito em Rust; o backend imediato é wat (texto WAT) → wasm-tools → wasmtime.

3. Invariantes do Domínio

1. Determinismo: Um mesmo plasmid.toml deve produzir um mesmo plasmid.wasm byte-a-byte (content addressing estável).
2. Imutabilidade pós-compilação: o plasmídeo, uma vez compilado e assinado, é um CausalBlock — não é editável, apenas substituído.
3. Sandbox obrigatório: zero syscalls fora do host imports declarado; o wasmtime aplica fuel e memória limitada.
4. Recibos Soberanos: toda execução emite um recibo DRE com referência ao CID do plasmídeo (ver Dicionário · DRE).
5. Idempotência de invocação: o mesmo (plasmid_cid, input_cid) produz o mesmo (output_cid, receipt_cid).

4. Veja também

• Referência · DSL de Plasmídeos
• Referência · WASI-PAEBIRU ABI
• Dicionário · Plasmídeo
• Arquitetura · Bounded Contexts
• ROADMAP

🔐 ZK (Zero-Knowledge)

O Bounded Context de ZK é a oficina de provas de conhecimento zero do PAEBIRU. Sua função canônica é a ZK-PoL (Proof of Location — provar que o nó está dentro de uma região geográfica sem revelar suas coordenadas exatas), mas também abriga provas de integridade de modelos federados e de correção de rollback C.A.P.I.B.A. O canônico é Groth16 sobre BN254, com arkworks como backend.

⚠️ Stub documental. O crate paebiru-zk ainda não está implementado no workspace (somente o kernel está materializado em crates/). Este arquivo existe para (a) desbloquear o build do mdBook em modo strict — o SUMMARY.md precisa de um capítulo apontando para o BC ZK — e (b) servir de contrato canônico para a primeira implementação. Ver tópico em formalização.

1. Fronteira do BC

2. Estado atual e roadmap

• Pré-Fase 3 — apenas especificado.
• O modelo matemático está descrito em Referência · Matemática.
• A prova de ZK-PoL combina (a) constraint Haversine para a distância geodésica com (b) constraint bounding-box para o raio autorizado, sem revelar a posição exata.
• Quando o nó rodando em MCU restrito não pode gerar a prova localmente, ela é delegada a um nó vizinho com attestation — o resultado entra como CausalBlock separado assinado por AMBOS os nós.

3. Invariantes do Domínio

1. Soundness acima de tudo: nenhuma prova aceita sem verificação completa do verifier; verificação parcial é proibida (anti-class: trusted setup trap).
2. SRS público e verificável: a structured reference string deve ser gerada por cerimônia pública verificável; nunca SRS descartável.
3. Sem replay: cada prova inclui um nonce causal derivado do DVV atual — provas velhas não são reusáveis.
4. Falha visível: prova inválida → recibo com verdict=reject
   • entrada no MacrophageVM para análise; nunca fail-silent.
5. Pós-quântico em roadmap: Groth16/BN254 é o canônico de Fase 3; transição para STARKs ou PLONK sobre curvas pós-quânticas será objeto de nova RFC.

4. Veja também

• Referência · Matemática · Groth16
• Runbook · R010 · Falha de ZK-PoL
• Dicionário · PoL
• Dicionário · ZK-PoL
• Arquitetura · Bounded Contexts

🧠 Neuromórfica

A visão neuromórfica trata a malha PAEBIRU como um cérebro sintético, onde cada nó é um neurônio e as mensagens são sinapses.

1. Processamento Baseado em Eventos

Diferente do processamento contínuo, a arquitetura neuromórfica reage a mudanças. O uso de SNN (Spiking Neural Networks) permite que o sistema permaneça em estado de baixa energia até que um estímulo relevante ocorra.

2. Plasticidade Sináptica

A rede aprende e se adapta através da mudança de “pesos” nas rotas de GossipSub. Caminhos que transmitem informações úteis (Recibos Soberanos validados) tornam-se mais fortes, enquanto rotas ruidosas são atrofiadas.

3. Computação no Substrato

A meta de longo prazo é rodar o PAEBIRU em hardware neuromórfico dedicado (ex: Loihi), explorando a física do silício para realizar computação de baixíssima entropia.

🚀 Espaço

PAEBIRU no espaço: Lidando com latências extremas, radiação e janelas de comunicação intermitentes.

1. Maturidade Causal em Longas Distâncias

Em redes espaciais, o tempo cronológico perde o sentido devido ao atraso de propagação. A Maturidade Causal (DVV) permite que satélites e estações terrestres se sincronizem sem depender de um relógio comum estável.

2. Tolerância a Falhas e Radiação

O sistema utiliza Reed-Solomon e redundância biológica (múltiplas cópias de plasmídeos) para sobreviver a corrupções de memória causadas por radiação cósmica, recuperando o estado a partir de peers vizinhos.

3. MuleNodes Orbitais

Satélites de órbita baixa (LEO) atuam como MuleNodes, transportando “lotes de conhecimento” entre regiões da Terra que não possuem conectividade direta via rádio ou fibra.

⚔️ Tática

Operação do PAEBIRU em cenários contestados, onde a rede pode sofrer interferência deliberada (jamming) ou censura agressiva.

1. Ofuscação de Tráfego

Uso de transporte mutável (libp2p multi-transports) para esconder o tráfego da malha dentro de outros protocolos ou através de saltos de frequência em rádio (LoRa).

2. Redes de Emergência

Em cenários de desastre, o PAEBIRU cria redes ad-hoc imediatas. A identidade soberana garante que o comando e controle permaneçam íntegros mesmo sem infraestrutura de internet.

3. ZK-PoL para Validação de Campo

Uso de Proof of Location para garantir que uma informação (ex: relatório de sensor) venha realmente da coordenada geográfica alegada, sem revelar a posição exata do operador para o inimigo.

🏛️ Governança

No PAEBIRU, a governança não é um processo burocrático externo, mas uma propriedade intrínseca do código e da economia, gerida por Plasmídeos de Governança.

1. Soberania Individual

Cada nó é soberano sobre sua identidade e recursos. Nenhuma decisão global pode forçar um nó a agir contra seu Veto Algedônico.

2. DAOs Estigmérgicas

Decisões coletivas emergem do rastro deixado pelos nós na malha. Propostas são plasmídeos que atraem ou repelem o “voto” (recursos computacionais) dos participantes conforme sua maturidade causal.

3. Voto Quadrático e Crédito Mútuo

O peso nas decisões de governança é balanceado pelo saldo no LandauerLedger, utilizando mecanismos como voto quadrático para evitar a plutocracia e incentivar a contribuição real para o ecossistema.

🌫️ Fog Computing

A visão de Fog Computing posiciona o PAEBIRU como a camada de “névoa” que reside entre os dispositivos IoT (edge) e a nuvem (cloud).

1. Hierarquia de Tiers

• Edge Tier: MuleNodes processando dados locais e emitindo recibos.
• Fog Tier: Nós de alta performance realizando agregação federada (FedAvg) e armazenamento quente (Correnteza).
• Cloud Tier: Snapshots imutáveis e auditoria global (Oceano).

2. Escalonamento Adaptativo

O scheduler de enxame utiliza o Hamiltoniano de Ising para distribuir tarefas de computação entre os nós da névoa, minimizando a latência e o consumo de energia total do cluster local.

3. Island Mode

Em caso de perda de conexão com a WAN, o cluster de névoa entra em Modo Ilha, mantendo a operação local e sincronizando o estado causal assim que a conectividade for restaurada.

🏭 Bioindustrial

Esta visão descreve a aplicação do PAEBIRU em ambientes de automação industrial, biorreatores e infraestrutura crítica, onde a resiliência e a Homeostasia são vitais.

1. Monitoramento Metabólico

Em uma planta industrial, sensores Modbus e CAN bus são tratados como entradas metabólicas. O nó PAEBIRU local atua como uma membrana que filtra o ruído e emite apenas sinais de relevância (spikes) para a malha.

2. Controle Descentralizado

Diferente de PLCs centrais, o controle é distribuído em Agentes ABAPORU que residem em cada máquina. Eles se coordenam estigmergicamente para otimizar o fluxo de produção sem depender de um servidor SCADA centralizado.

3. Segurança Crítica

O ZeroTrustPipeline garante que comandos de controle (plasmídeos) sejam validados criptograficamente antes da execução, protegendo a planta contra sabotagem digital ou injeção de comandos maliciosos.

🧠 Fundamentos teóricos

Por trás de cada decisão de projeto no PAEBIRU há um fundamento teórico — cognitivo, termodinâmico, ou de coordenação. Esta seção é a trilha conceitual: leia antes (ou durante) mergulhar no código.

Ensaios canônicos

Leituras externas recomendadas

Esta é uma biblioteca comentada, não uma checklist. Escolha por interesse e tempo disponível.

Cibernética & sistemas adaptativos

• W. Ross Ashby — An Introduction to Cybernetics (1956) — livro-texto fundador; “lei da variedade requerida” é a base do nosso sensor algedônico.
• Donella Meadows — Thinking in Systems (2008) — vocabulário para “membrana” e “estoque vs fluxo”.
• Francisco Varela, Humberto Maturana, Ricardo Uribe — Autopoiesis — a base生物学 do nosso modelo de “célula de malha”.

Distribuídos & consenso

• Leslie Lamport — Time, Clocks, and the Ordering of Events (1978) — a referência de Maturidade Causal.
• Diego Ongaro, John Ousterhout — In Search of an Understandable Consensus Algorithm (Raft, 2014) — referência para a parte síncrona local.
• Cynthia Dwork, Nancy Lynch, Larry Stockmeyer — Consensus in the Presence of Partial Synchrony (1988) — modelo de partição.

Termodinâmica da computação

• Rolf Landauer — Irreversibility and Heat Generation in the Computing Process (1961) — base do LandauerLedger.
• Edward Nelson — Dynamical Theories of Brownian Motion (1967) — referência para a equação de Langevin.
• Luca Peliti — Statistical Mechanics in a Nutshell (2011) — capítulo sobre o Hamiltoniano de Ising.

Neuromórfica

• Wolfgang Maass — Networks of Spiking Neurons (1997) — base da nossa SNN.
• Carver Mead — Analog VLSI and Neural Systems (1989) — base do HAL neuromórfico.

Como ler

1. Se você é novato no projeto: comece por Arquitetura cognitiva.
2. Se você está mexendo em consenso / partição: vá para Protocolos de coordenação.
3. Se você está mexendo em scheduler / backpressure: Fundamentos termodinâmicos.

Veja também

• Dicionário canônico — termos do projeto
• Arquitetura — Bounded Contexts
• Manifesto — as 7 teses

🧠 Arquitetura Cognitiva

O PAEBIRU não é apenas um sistema de mensagens; ele é um organismo distribuído. Sua arquitetura cognitiva é baseada no modelo ABAPORU, que combina a lógica clássica de agentes autônomos com a biologia neuromórfica.

1. O Agente ABAPORU (BDI)

Cada nó PAEBIRU executa uma instância do ABAPORU, seguindo o framework Belief-Desire-Intention (BDI):

• Percepção: O nó recebe estímulos (spikes da SNN, mensagens do gossipsub, sinais algedônicos).
• Crenças (Beliefs): O nó mantém um grafo causal do ambiente.
• Desejos (Desires): Objetivos latentes (ex: manter-se energizado, processar rounds de aprendizado).
• Intenções (Intentions): Compromissos de ação imediata (ex: assinar um recibo, propagar um plasmídeo).

2. Redes de Spikes (SNN) e Atenção

Diferente das IAs tradicionais de “caixa preta”, a cognição do PAEBIRU é esparsa e temporal:

• SNN (Spiking Neural Networks): Neurônios LIF (Leaky Integrate-and-Fire) processam informações apenas quando ocorrem mudanças significativas (spikes), reduzindo o custo termodinâmico.
• Atenção Estigmérgica: O nó foca sua capacidade computacional em áreas da malha onde o “rastro” (estigmergia) é mais forte, permitindo uma coordenação global sem supervisor central.

3. Algedonia e Feedback Homeostático

A cognição é guiada por dor e prazer:

• Sinais de Dor: Saturação de recursos, ataques detectados ou perda de conectividade.
• Sinais de Prazer: Eficiência energética, convergência de modelos e integridade causal.
• Loop de Feedback: O agente ajusta seu comportamento para minimizar a dor e maximizar a Homeostasia local.

4. Cognição Fractal

A inteligência é recursiva:

1. Uma função WASM tem uma cognição primitiva de entrada/saída.
2. Um plasmídeo coordena várias funções.
3. Um nó coordena plasmídeos.
4. A malha coordena nós. Cada escala utiliza o mesmo ciclo de processamento, mudando apenas a complexidade das crenças.

5. Veja também

• BC Biologia
• BC Aprendizado
• Dicionário · ABAPORU
• Teoria · Fundamentos Termodinâmicos

🤝 Protocolos de Coordenação

No PAEBIRU, a coordenação entre milhares de nós heterogêneos não é feita por comando central, mas por mecanismos emergentes inspirados em sistemas biológicos e sociais.

1. Estigmergia e Coordenação Indireta

A Estigmergia é o mecanismo onde os agentes se coordenam modificando o ambiente:

• Rastros Causais: Cada Receipt e CausalBlock deixa um rastro no storage (C.A.P.I.B.A.) e na rede.
• Atração de Atenção: Novos plasmídeos e mensagens são atraídos para áreas de alta atividade estigmérgica, criando uma organização natural de carga.

2. GossipSub e Difusão Epidêmica

O transporte de informação segue modelos epidemiológicos:

• Gossip: As informações (pulsos, recibos, plasmídeos) “vazam” entre nós vizinhos.
• Robustez: Mesmo com falhas massivas de nós, a informação eventualmente alcança todos os interessados devido à redundância inerente ao protocolo GossipSub.
• Backpressure de Rede: O fluxo de gossip é limitado pelo metabolismo do nó, evitando tempestades de broadcast.

3. Consenso por Maturidade Causal (DVV)

Ao contrário de blockchains que exigem uma ordem linear global (timestamp ou bloco), o PAEBIRU utiliza Maturidade Causal:

• Dotted Version Vectors (DVV): Capturam a relação “aconteceu-antes” (happened-before).
• Consenso Local: Pequenos grupos de nós (LocalSyncDomains) concordam com o estado causal de forma rápida, sem esperar a malha global.
• Convergência Eventual: A malha global converge para o estado de maior maturidade causal ao longo do tempo.

4. Quóruns Adaptativos e FROST

Para operações críticas que exigem confiança:

• FROST: Uso de assinaturas de limiar (threshold signatures) onde $t$ de $n$ nós assinam uma decisão.
• Identidade Distribuída: A soberania não reside em um nó, mas na capacidade do grupo de gerar um recibo válido.

5. Veja também

• Dicionário · Estigmergia
• Dicionário · Maturidade Causal
• BC Kernel
• Referência · Matemática

⚡ Fundamentos Termodinâmicos

O PAEBIRU é construído sobre a premissa de que a computação é um processo físico sujeito às leis da termodinâmica. Ignorar o custo energético da informação leva a sistemas centralizados e ineficientes.

1. Princípio de Landauer e o Custo do Esquecimento

O físico Rolf Landauer demonstrou que apagar um bit de informação dissipa calor: $$Q \geq k_B T \ln 2$$

• LandauerLedger: Cada operação de segurança e armazenamento no PAEBIRU debita um custo termodinâmico real.
• Incentivo à Eficiência: Algoritmos que minimizam a entropia (esquecimento desnecessário) são economicamente favorecidos na malha.

2. Dinâmica de Langevin e o Tempo

O tempo no sistema não é uma constante cronológica, mas uma variável da Dinâmica de Langevin:

• Δt ∝ ΔS / γ: O tempo (o tick do sistema) avança apenas quando há variação de entropia ($\Delta S$) vencendo o atrito metabólico ($\gamma$).
• Estocasticidade: O sistema aceita o ruído como parte natural do processo de busca por estados de equilíbrio (Langevin SGD).

3. Homeostasia e Dissipação de Calor

Cada nó deve manter seu equilíbrio térmico e de recursos:

• Algedonia: O sistema de dor/prazer é a representação subjetiva do estado entrópico do nó.
• Veto Algedônico: A proteção física final do nó contra a exaustão térmica.
• Metabolismo: A taxa na qual o nó pode “digerir” informação sem entrar em colapso.

4. Computação de Baixa Entropia

O uso de SNN (Spiking Neural Networks) e Zero-Copy visa reduzir a dissipação de energia:

• Zero-Copy: Evitar cópias de memória reduz o trabalho físico total.
• Sparsity: Processar apenas o que muda (spikes) preserva a energia do nó para tarefas críticas.

5. Veja também

• Dicionário · LandauerLedger
• Dicionário · Langevin Ticks
• BC Entropia
• Referência · Matemática

📖 Dicionário canônico

Este documento é a fonte de verdade para todos os termos técnicos do PAEBIRU. Em caso de divergência entre este dicionário, o AGENTS.md, comentários de código ou RFCs, este dicionário prevalece até que uma RFC Standards Track atualize-o formalmente.

Convenção: cada entrada traz a forma canônica em pt-BR, a sigla, o termo em inglês quando útil, e a referência à RFC que o ratifica (se houver).

A

ABAPORU (Agente BDI)

Nome em tupi para “homem que come”) — agente de crença-desejo-intenção que opera no BC Biologia. Implementação canônica em paebiru-biology.

Veja tópico em formalização e BC Biology.

Algedonia / Algedonic Sensor

Literalmente, “dor e prazer” (do grego algos + hedone). Sensor que emite sinais de dor quando a homeostasia é violada (temperatura, memória, backpressure, saturação XDP) e prazer quando o sistema opera dentro da faixa saudável. Cada escala tem o seu — não existe supervisor global.

tópico em formalização.

Anti-padrão “Costura”

Acoplamento por tipo ou estado compartilhado entre Bounded Contexts (Arc<Mutex<T>> cruzando membrana). Sintoma de fronteira mal colocada. Refatora-se a membrana; nunca se costura.

tópico em formalização.

Anti-padrão “supervisor global”

Qualquer coordenador que conhece o estado de N escalas abaixo. Empurre a decisão para a escala que sofre a consequência.

tópico em formalização.

Auto-similaridade fractal (Padrão Antropofágico)

O ciclo ingerir → metabolizar → excretar repete-se em 7 escalas: bit físico → neurônio LIF → função WASM → plasmídeo → nó ABAPORU → LocalSyncDomain → malha global.

tópico em formalização, Realidade fractal.

Antígeno / Anticorpo

Antígeno: pacote ou plasmídeo marcado como suspeito pelo ZeroTrustPipeline. Anticorpo: plasmídeo WASM sintetizado pela MacrophageVM após análise do antígeno; subsequentemente distribuído como “imunidade” aos outros nós.

tópico em formalização.

B

Backpressure universal

O produtor adapta-se ao consumidor mais lento via sinal explícito (token bucket, créditos). Nunca buffer infinito. A forma é idêntica em streaming payments, FL gradient updates e gossipsub fanout.

tópico em formalização.

BLAKE3

Função de hash criptográfica usada em toda a pilha (PoW, DVV, identidade, integridade de plasmídeos). Preferida sobre SHA-256 por throughput, tree hashing nativo e segurança pós-quântica marginal.

tópico em formalização.

Bounded Context (BC)

Granularidade vertical do PAEBIRU: cada BC mapeia 1:1 com um crate. Comunica-se com outros BCs apenas por artefatos imutáveis com receipt. Lista canônica: kernel, biology, economy, capiba, entropy, learning, api, bridges, commons, hal, zk, plasmids.

Arquitetura.

Convenção editorial: grafia sempre em Title Case — Bounded Context e Bounded Contexts (plural), mesmo em meio de frase. A forma minúscula bounded context(s) é reservada a citações textuais do termo DDD genérico.

C

CausalBlock

Unidade imutável básica do C.A.P.I.B.A.: tupla (cid, maturidade, dados, assinaturas) endereçada por content ID (BLAKE3). É o “átomo” que migra entre estágios (Nascente → Correnteza → Manguezal → Oceano → Chuva) e entre nós (via Pororoca Causal). Recebe um Recibo Soberano (DRE) a cada transição de estágio.

BC C.A.P.I.B.A..

C.A.P.I.B.A. (Causal, Asynchronous, Persistent, Immutable Block Architecture)

A memória de longo prazo do PAEBIRU — onde kernel lida com a mensagem em trânsito, capiba lida com a mensagem em repouso: como ela vira dado, como o dado vira conhecimento, e como o conhecimento se preserva no tempo causal. Não é “um banco de dados”: é um ecossistema metabólico de dados organizado em 5 estágios análogos ao ciclo hidrológico:

Princípios vinculantes (cada item é rejeição automática em revisão):

1. Tempo causal, não cronológico — ordenação por DVV, jamais por Instant::now().
2. Content addressing — blocos endereçados por (hash_conteúdo, maturidade_causal), não por path.
3. Apoptose saudável — MUS (Minimum Useful Survival) define a maturidade abaixo da qual o dado evapora; a Landauer Gate assegura que o custo termodinâmico da retenção respeite $k_B \cdot T \cdot \ln 2$.
4. Sovereignty Gate — antes de descer para o Oceano, dados são auditados (CDDL + validação semântica + ZK-PoL se houver geolocalização).
5. Compute-over-data > move-data — a Chuva (compute) vai até o Oceano (storage), não o contrário.
6. Quarentena imunológica — o Manguezal é filtro Zero-Trust; “lama tóxica” vai para MacrophageVM.
7. Sincronização MuleNode — MuleNodes (LoRa, ATmega) sincronizam via Pororoca Causal — batched, eventual, com receipts imutáveis.
8. Backpressure de I/O — profundidade finita do WAL; produtor adapta-se ao consumidor (jamais buffer infinito).

Quando $\Delta C \to 0$ (taxa de novas interações com o bloco) e a maturidade causal excede MUS, o dado evapora do Manguezal para o Oceano. Quando $\Delta C \to 0$ no Oceano, ele pode ser chuva — entrar em compute-over-data para virar um plasmídeo (regra distribuída).

RFCs normativas: tópico em formalização (definição), tópico em formalização (CID IPLD), tópico em formalização (apoptose), tópico em formalização (Iceberg), tópico em formalização (Landauer Gate). BC doc canônico: architecture/bounded-contexts/capiba.md.

CDDL (Concise Data Definition Language)

Linguagem usada para definir o contrato de dados no Portão 5 do ZeroTrustPipeline. Validação semântica antes de qualquer plasmídeo ser executado.

tópico em formalização.

Cifra ChaCha20-Poly1305

Cifra simétrica AEAD canônica do PAEBIRU. Usada em todos os envelopes de plasmídeo e em sessões TLS-like entre nós.

tópico em formalização.

CommonCrypto

Sinônimo coloquial para a pilha criptográfica canônica: BLAKE3 + ed25519-dalek + FROST + ML-DSA/ML-KEM + ChaCha20-Poly1305.

Compute-over-data

Padrão pelo qual o dado permanece no nó de origem e a computação viaja até ele — oposto do modelo “traga o dado até o lago”. Custódia, soberania e economia são co-locadas.

BC C.A.P.I.B.A..

Crédito mútuo (DRE)

Sistema de crédito bilateral plurilateral, soma zero, sem juros explicitos. Liquidação por compensação multilateral periódica. NÃO é “criptomoeda”: é um tecido entre agentes que se conhecem.

tópico em formalização, tópico em formalização.

Convenção editorial: grafia sempre em Title Case quando substantivo próprio (Crédito mútuo). A forma adjetiva creditário mútuo é aceitável apenas em textos técnicos formais sobre o modelo.

D

Dança Politemporal (v3+)

Regime temporal em que $\Delta t \propto \Delta S / \gamma$ — o “tempo” se dilata quando a entropia cresce, e se contrai quando nada varia. Múltiplos “tempos” coexistem sem hierarquia.

tópico em formalização, BC Entropia.

DRE (Distributed Receipt Engine)

Motor de Recibos Soberanos. Cada interação produz um recibo imutável com hash, assinatura ML-DSA, timestamp causal e custo em LandauerLedger. É a unidade atômica de prova.

tópico em formalização.

DVV (Dotted Version Vector)

Estrutura que captura maturidade causal, não cronologia. Cada nó tem um vetor de versões por origem; um evento “amadurece” quando todos os seus dependentes causais também amadureceram. É a base da Maturidade Causal.

tópico em formalização.

E

eBPF / XDP

Tecnologia Linux para executar programas no kernel com segurança. O Portão 1 (Load Shedder) do ZeroTrustPipeline é um programa XDP carregado pelo paebiru-kernel via aya.

tópico em formalização.

Estigmergia

Coordenação indireta entre agentes via modificação do ambiente compartilhado. No PAEBIRU: rastros de plasmídeo, receipt em WAL, memória C.A.P.I.B.A., e gradiente algedônico.

tópico em formalização.

F

Fail-stop em 7 escalas

Falha imediata, sem retry silencioso, em qualquer das 7 escalas fractais. Acima de um limiar algedônico, o nó emite Veto Algedônico e interrompe a operação local; nunca propaga falha.

tópico em formalização.

FedAvg / Split-DNN / FLAIR

Família de algoritmos de aprendizado federado suportados em paebiru-learn. Agregação bizantina (Krum, FoolsGold) é obrigatória em redes > 50 nós.

tópico em formalização, tópico em formalização.

FROST (Flexible Round-Optimized Schnorr Threshold)

Esquema de assinaturas threshold (DPSS) usado para chaves distribuídas. Em 3-de-5, três nós assinam; dois podem sair do ar sem perda de soberania.

tópico em formalização.

G

GALS (Globally Asynchronous, Locally Synchronous)

Paradigma fundamental: atores localmente síncronos, comunicação globalmente assíncrona via troca de mensagens. Dogma 2 .

Arquitetura.

GossipSub

Protocolo de publish-subscribe baseado em gossip do libp2p. É o transporte default de plasmídeos e receipts.

H

HAL (Hardware Abstraction Layer)

Runtime no_std para ESP32, STM32, nRF52, ATmega e RISC-V. Fornece traits de GPIO, ADC, UART, I²C, SPI, LoRa, CAN, Modbus.

BC HAL.

Hardware Wallet

Dispositivo físico que custodia a chave de identidade soberana (comunica-se com TPM ou Secure Enclave). Suportado em paebiru-hal com bindings USB.

tópico em formalização.

HardwarePassport

Dispositivo físico de backup de identidade soberana — distinto do Hardware Wallet. O Passport é um artefato off-line (sem conectividade, à prova de tamper) que carrega (a) a chave mestra criptografada por biometria/PUK, (b) o último DVV conhecido do nó, e (c) o último Recibo Soberano assinado. Usado no protocolo de Disaster Recovery quando o nó primário é perdido (ver R011 · Disaster recovery).

Homeostasia

Tendência de um sistema a manter variáveis internas dentro de uma faixa saudável. Emerge de sensores algedônicos locais, sem supervisor global.

I

Ilha de autonomia

Regime operacional em que um conjunto de nós opera sem WAN, com partição interna. Sincroniza DVV e receipts quando reconecta.

tópico em formalização.

Convenção editorial: grafia canônica Ilha de autonomia ou forma abreviada Modo Ilha (ambas aceitas). A forma inglesa Island mode é proibida em documentação pt-BR.

Imunidade distribuída

Conjunto de anticorpos (plasmídeos WASM) compartilhados entre nós após análise em MacrophageVM. Não é uma blacklist central — é conhecimento emergente.

L

LandauerLedger

Livro de débitos energéticos. Cada operação no ZeroTrustPipeline debita um custo em µJ (PAEBIRU_GATE_SECURITY_COST_MICRO_JOULES). É a base de reciprocidade material do crédito mútuo.

BC Entropia.

Landauer Gate

Portão termodinâmico que decide se um CausalBlock tem energia associada suficiente para ser retido, ou se deve evaporar. A regra operacional respeita o princípio de Landauer: o custo mínimo de apagar 1 bit é $k_B \cdot T \cdot \ln 2$ joules. Se o custo de retenção (energia de armazenamento + indexação) excede o benefício causal ($\Delta C$), o portão dispara apoptose saudável e o bloco migra para o Oceano ou evapora.

BC C.A.P.I.B.A. · Princípios.

Langevin Ticks

Unidade de tempo baseada na dinâmica de Langevin — estocástica, termodinamicamente fundamentada. No regime v3+ é a base da Dança Politemporal.

tópico em formalização, Equações de Langevin.

Lote / Loteria Joule

Lote: agrupamento de receipts em intervalos Langevin. Loteria Joule: protocolo pelo qual o sistema recompensa contribuições de poder computacional real, em ordem causal, com soma zero.

tópico em formalização.

LocalSyncDomain

Uma das 7 escalas fractais do Padrão Antropofágico (ver Auto-similaridade fractal): agrupamento de nós que compartilham um relógio Langevin e trocam CausalBlocks síncronamente. Corresponde à 6ª escala, entre o nó ABAPORU (5ª) e a malha global (7ª). Limites operacionais típicos: 3-50 nós, 1-100 km de raio, latência P99 < 50 ms.

Realidade fractal.

M

MacrophageVM

Sandbox WASM (rodando em wasmtime) onde pacotes suspeitos são fagocitados e analisados em profundidade. Sintetiza anticorpos.

tópico em formalização.

Maturidade Causal

Propriedade de um evento: ele “amadureceu” quando todos os seus dependentes causais também amadureceram. Ordenação por DVV, não por relógio. Em partições longas, a “idade causal” diverge da “idade cronológica” — é por design.

tópico em formalização, M/M/1 modelagem.

ML-DSA (Module-Lattice-Based Digital Signature Algorithm)

Assinatura digital pós-quântica (FIPS 204). Default em receipts e autenticação mútua. Antes: ML-DSA-65.

tópico em formalização.

ML-KEM (Module-Lattice-Based Key-Encapsulation Mechanism)

Encapsulamento de chaves pós-quântico (FIPS 203). Usado em sessão inicial entre dois nós.

MuleNode / MuleReceipt

MuleNode: nó de borda de recursos extremamente limitados (LoRa SX1262, ATmega, ESP32 em modo sleep profundo) que serve como ponte offline entre ilhas de autonomia. Não mantém DVV completo; acumula receipts locais e sincroniza em lote quando encontra outro nó (“mula” carregando dados). Sincroniza via protocolo Pororoca Causal — batched, eventual, com receipts imutáveis (cada batch emite um MuleReceipt resumido).

BC C.A.P.I.B.A., MANIFESTO § Soberania por Design.

MUS (Minimum Useful Survival)

Limiar de maturidade causal abaixo do qual um CausalBlock é candidato à apoptose saudável. Quando a Maturidade Causal de um bloco cai abaixo de MUS e sua taxa de novas interações $\Delta C \to 0$, o bloco evapora (a Landauer Gate decide o destino final). Parâmetro ajustável por nó, com mínimo absoluto garantido pelo Dicionário.

BC C.A.P.I.B.A..

O

Oceano

Camada de armazenamento fria, off-line, eventualmente consistente, para dados com $\Delta C \to 0$. Não serve plas quentes — apenas auditoria e reconstrução pós-morte.

BC C.A.P.I.B.A., R009 · Migração para Oceano.

P

Plasmídeo (DSL → WASM)

Unidade de código de contrato. Definido em TOML/HCL, compilado pelo paebiru-plasmids para um módulo WASM, executado em wasmtime dentro de uma membrana C.A.P.I.B.A.

tópico em formalização, DSL de Plasmídeos.

Pulse (Pulso)

Mensagem metabólica de homeostase trocada entre nós PAEBIRU, definida em crates/kernel/src/ports/mod.rs:31-36 como o enum MetabolicMessage::{PulseRequest, PulseResponse}. Funções canônicas:

1. Sinal de vida (heartbeat) — emitido periodicamente (período padrão de 10s, configurável via DEFAULT_PULSE_PERIOD em apps/node/src/lib.rs).
2. Atualização de saúde — cada PulseResponse carrega um health: f32 ∈ [0.0, 1.0] que alimenta o PeerHealth no Metabolism (ver BC Kernel) e, em última instância, o AlgedonicSensor local.
3. Re-sincronização causal — em nós congelados, dispara avanço do Langevin Tick (ver R008 · Langevin Clock Drift).
4. Anúncio na malha — ao ser publicado, o nó se torna visível para os peers no mesh gossipsub.

Transporte: gossipsub (tópico paebiru-metabolism). Descoberta dos pares: mDNS (LAN) + Kademlia DHT (global, via PAEBIRU_BOOTNODES). O pulso não é armazenado na DHT — ele flui ponto-a-ponto sobre conexões estabelecidas via descoberta.

Gate F1 do Roadmap: “dois nós trocam pulse ponta-a-ponta via libp2p Kademlia” — o critério de aceite do relé DHT é a troca de PulseRequest/PulseResponse ponta-a-ponta. BC Kernel, Hello, mesh.

Pororoca Causal

Protocolo de sincronização batched usado por MuleNodes (LoRa, ATmega) para reconciliar DVV e CausalBlocks entre ilhas de autonomia sem WAN contínua. O nome alude à pororoca (onda de maré que percorre o rio Amazonas contra a corrente): os dados viajam “contra” a partição de rede, em pulsos agregados, até encontrar um nó on-line. Cada pulso emite um MuleReceipt resumido e assinado.

BC C.A.P.I.B.A..

PoL (Proof of Location)

Prova de localização física preservando privacidade das coordenadas exatas. Construída via zk-SNARK Groth16.

tópico em formalização, R010 · Falha de ZK-PoL.

Portão / Gate

Cada um dos 5 estágios do ZeroTrustPipeline. Cada portão é opcionalmente desabilitável em dev via env var (PAEBIRU_SKIP_PF, etc.) — nunca em produção.

Prolly Tree

Árvore B+ com hashes determinísticos nos nós. Usada em C.A.P.I.B.A. para diffs pequenos em updates grandes.

tópico em formalização.

Q

Quórum adaptativo

Número mínimo de validadores para um receipt ser considerado final. Adapta-se ao tamanho da malha e à distância causal.

tópico em formalização.

R

Realidade fractal

Ver Auto-similaridade fractal.

Realidade fractal.

Recibo Soberano

Ver DRE.

Runbook vivo

Documento operacional que aprende com postmortems: cada incidente gera um patch no runbook correspondente. Versionado por git tag (runbook-vN).

tópico em formalização.

S

SPHINCS+

Assinatura pós-quântica stateless (FIPS 205). Usada como fallback do ML-DSA em cenários de limitação severa de banda.

Soberania

Princípio e estado: identidade enraizada em hardware, sem CA externo. Soberania é arquitetural, não contratual.

Sovereignty Gate

Portão de auditoria que todo CausalBlock deve atravessar antes de descer para o Oceano (cold storage). Combina três verificações: (1) CDDL — o bloco respeita o schema de dados contratado; (2) validação semântica — a carga é coerente com o tipo declarado; (3) ZK-PoL se houver dados de geolocalização. Falha em qualquer um = quarentena (MacrophageVM) + Recibo Soberano de verdict=reject.

BC C.A.P.I.B.A. · Princípios.

T

TPM (Trusted Platform Module)

Chip de silício que custodia chaves e atesta a integridade do firmware. Padrão para identidade soberana em nós com recursos suficientes.

R002 · Identidade TPM.

V

Veto Algedônico

Ação pela qual o hardware se sobrepõe a decisões de governança ao detectar dano físico iminente (temperatura > limiar, voltagem < mínimo, brown-out). Veto é local, imediato, e não negociável.

tópico em formalização.

Convenção editorial: grafia sempre em Title Case — Veto Algedônico (substantivo próprio), mesmo em meio de frase. A forma minúscula veto algedônico é reservada a citações textuais.

Voto Quadrático

Mecanismo de governança DAO em que o custo de um voto cresce quadraticamente com o número de votos que um agente emite sobre o mesmo tema: $C(n) = n^2$. Isso desencorrega plutocracia de whales e recompensa stake distribuído. Usado no PAEBIRU para decisões de protocolo que afetam toda a malha (mudança de parâmetros MUS, alteração de topologia default, ativação de novos plasmídeos canônicos).

View · Governança, tópico em formalização.

Z

ZeroTrustPipeline

Cadeia de 5 portões que todo pacote deve atravessar:

1. Load Shedder (eBPF/XDP)
2. Proof-of-Work (BLAKE3 salt + nonce)
3. Assinatura ML-DSA
4. ZK-PoL (Groth16)
5. Contrato de Dados (CDDL)

tópico em formalização.

ZK-PoL

Ver PoL.

Apêndice — Siglas invertidas

Política editorial

• Adições e mudanças substantivas exigem uma RFC (Standards Track ou Experimental) com aprovação de pelo menos um maintainer.
• Termos em inglês são aceitos quando consagrados pelo uso (ex: “GossipSub”); caso contrário, usar pt-BR.
• Conflitos com código ou comentários devem ser corrigidos no código, mantendo este dicionário como fonte.

📊 Benchmarks de Performance

Resultados automáticos da última execução do cargo bench.

Gerado automaticamente em: Mon Jun 8 22:02:08 UTC 2026

🧮 Fundações matemáticas

O PAEBIRU é um sistema distribuído termodinamicamente fundamentado. Esta página é o índice das ferramentas matemáticas que sustentam os principais protocolos. As provas formais vivem em crates/*/formal/ (TLA+ para concorrência, Lean 4 para pureza).

Sumário

1. Equações de Langevin
2. Hamiltoniano de Ising
3. Reed-Solomon sobre Corpos de Galois
4. Dotted Version Vectors (DVV)
5. Fórmula de Haversine
6. Análise Topológica de Dados (TDA)
7. Backpressure M/M/1
8. Groth16 (zk-SNARKs)
9. Verificação formal

Equações de Langevin

A dinâmica de Langevin governa o “tempo” do PAEBIRU:

$$ m , \frac{dv}{dt} = -\gamma v + \sqrt{2D} , \xi(t) + F_{\text{ext}} $$

Implicação para o scheduler: um Langevin Tick só avança quando a entropia local varia ($\Delta S \neq 0$). Sem variação, o sistema “congela” — por isso o regime v3+ chama-se Dança Politemporal (tópico em formalização; ainda sem número de RFC atribuído, conforme a regra de ouro do processo).

Modelo formal em Lean 4: crates/paebiru-math/formal/lean/Langevin.lean.

Hamiltoniano de Ising

Usado pelo scheduler de enxame e pelo consenso bizantino adaptativo. Modelo $N$ spins em rede $d$-dimensional:

$$ \mathcal{H} = -J \sum_{\langle i,j \rangle} s_i s_j - h \sum_i s_i, \quad s_i \in {-1, +1} $$

Onde:

• $J$ = acoplamento (positivo: ferromagnético; negativo: vidro de spin).
• $h$ = campo externo (urgência do scheduler).
• $\langle i, j \rangle$ = pares de vizinhos na malha.

O Ising solver (Fase 4) usa annealing simulado em paebiru-math para encontrar configurações de baixa energia — mapeando “tarefas” para “spins” e “custo” para “acoplamento”.

Reed-Solomon sobre Corpos de Galois

Usado em C.A.P.I.B.A. para reconstrução de blocos perdidos e correção de erros no WAL distribuído.

Dado mensagem $m = (m_0, \ldots, m_{k-1})$ em $\mathrm{GF}(2^8)$:

1. Codifica em polinômio $p(x) = m_0 + m_1 x + \cdots + m_{k-1} x^{k-1}$.
2. Avalia em $n$ pontos ($\mathrm{GF}(2^8)^* \cup {0}$).
3. Distribui $n$ símbolos; recupera com $k \leq n’ < n$ (decodificação de Berlekamp-Welch ou Sugiyama).

Por que RS, não LDPC? O custo de decodificação em MCUs é proibitivo para LDPC; RS é tabelável em ROM de 2 kB.

Prova formal em Lean 4: crates/paebiru-math/formal/lean/ReedSolomon.lean.

Dotted Version Vectors (DVV)

Um DVV é um mapeamento de identificadores de evento para contadores, estendendo Causal Version Vectors com a noção de “discrete snapshot”.

$$ D_v : \text{EventId} \to \mathbb{N}, \quad D_v(\text{evento}) = \text{contador no produtor} $$

• $D_v \sqsubseteq D_w$ significa “DVV $v$ é causalmente anterior a $D_w$”.
• União por componente: $D_v \sqcup D_w$ é o least upper bound.
• Maturidade Causal de um evento $e$ é a condição $D_e \sqsubseteq D_{\text{local}}$, isto é, todos os seus dependentes foram observados localmente.

tópico em formalização — referência normativa.

Fórmula de Haversine

Distância geodésica entre dois pontos na esfera ($\oplus$ = Terra, raio $R = 6371{,}0088$ km):

$$ d = 2R \cdot \arcsin!\left(\sqrt{\sin^2!\left(\frac{\Delta\phi}{2}\right) + \cos\phi_1 \cos\phi_2 \sin^2!\left(\frac{\Delta\lambda}{2}\right)}\right) $$

Usada em:

• PoL (ZK-PoL): circunscrição de raio garantido.
• Scheduler de proximidade: priorizar peers geograficamente próximos em redes LoRa (limites de tempo de propagação).

Implementação no_std em paebiru-math::geo::haversine_distance. Prova formal em Lean 4: Haversine.lean.

Análise Topológica de Dados (TDA)

Usada para detectar mudança de regime no comportamento da malha (saturação, deriva, partição).

A ferramenta central é a homologia persistente: dada uma nuvem de pontos $(x_i) \in \mathbb{R}^d$, constrói-se uma família de complexos simpliciais (Vietoris-Rips) e computa-se a persistência de cada classe homológica ($\beta_0$, $\beta_1$).

• Classes de vida longa → estrutura topológica real.
• Classes de vida curta → ruído.

Em Rust, integração com rust_tda (Fase 4) ou com bindings para gudhi (Python).

Modelagem de filas M/M/1

Para dimensionar buffers, backpressure e latência do ZeroTrustPipeline.

Consulte queues-model.md para a derivação completa de Little, Pollaczek-Khinchine e o regime de Langevin adaptativo.

Groth16 (zk-SNARKs)

zk-SNARK de referência usado no ZK-PoL. Setup confiável $S$ produz:

• Chave de prova: $\text{pk} \in \mathbb{G}_1^{n+l} \times \mathbb{G}_2^{n}$.
• Chave de verificação: $\text{vk} \in \mathbb{G}_1 \times \mathbb{G}_2^2$.
• Prova: $\pi \in \mathbb{G}_1 \times \mathbb{G}_2$.

Para o PoL, o circuito verifica: “a posição $p$ está dentro do disco de raio $r$ centrado em $c$, sem revelar $p$ nem $c$.”

Curvas alvo: BN254 (default) e BLS12-381 (Fase 4). Mais em BC ZK.

Verificação formal

A verificação formal do PAEBIRU é cirúrgica: TLA+ para concorrência e estado global, Lean 4 para pureza algorítmica.

Acionada por make verify-formal.

Veja também

• Dicionário canônico — termos, não fórmulas.
• Filas M/M/1 — modelagem detalhada de filas.
• Padrões — receitas algorítmicas recorrentes.
• Verificação formal (guia de contribuidor).

📊 Modelagem de Filas (M/M/1)

O PAEBIRU utiliza a teoria das filas para dimensionar o ZeroTrustPipeline e o sistema de Backpressure. O modelo M/M/1 serve como aproximação para o processamento de mensagens em um único nó.

1. Definições

• λ (Lambda): Taxa média de chegada de mensagens (mensagens/seg).
• μ (Mu): Taxa média de serviço do nó (mensagens/seg).
• ρ (Rho): Intensidade de tráfego ($\rho = \lambda / \mu$).

2. Invariantes de Performance

Para manter a estabilidade metabólica, o nó deve operar em $\rho < 1$.

• Tempo Médio no Sistema ($W$): $W = 1 / (\mu - \lambda)$.
• Número Médio de Mensagens no Sistema ($L$): $L = \lambda / (\mu - \lambda)$.

3. Regime de Langevin Adaptativo

Quando $\rho \to 1$, o sensor algedônico dispara o sinal de dor, reduzindo $\lambda$ através da emissão de tokens de backpressure. No regime v3+ (Dança Politemporal), isso causa a dilatação do tempo local para permitir que o nó processe o acúmulo de mensagens sem dissipar calor excessivo.

4. Aplicação no ZeroTrustPipeline

Cada portão (1 a 5) atua como um servidor em uma fila serial. A latência total é a soma das latências de cada portão: $$T_{total} = \sum_{i=1}^{5} \frac{1}{\mu_i - \lambda}$$

5. Veja também

• BC Entropia
• Teoria · Fundamentos Termodinâmicos
• Referência · Matemática

🧩 Padrões e Receitas

Lista de padrões arquiteturais e algoritmos recorrentes no ecossistema PAEBIRU.

1. Padrão Antropofágico (Fractal)

O ciclo ingerir → metabolizar → excretar deve ser aplicado em todas as escalas. Se você está criando um novo subsistema, ele deve ter:

• Uma entrada de dados/eventos.
• Um loop de processamento (metabolismo).
• Uma saída de resultados/recibos.
• Um sensor algedônico local.

2. Receptor-Reator

Nenhum componente deve agir de forma proativa sem um estímulo. Todo processamento é uma reação a um pulso metabólico ou mensagem de rede, garantindo que o sistema economize energia quando não há demanda.

3. Opaque Handles (FFI)

Nunca exponha tipos Rust complexos em bindings. Use ponteiros *mut c_void e funções de acesso para garantir que a memória seja gerida de forma segura e que o layout interno dos structs possa mudar sem quebrar os SDKs.

4. Veja também

• Qualidade · 4 Dogmas
• Realidade Fractal
• Dicionário

🛠️ CLI do Forge

A CLI do Forge (paebiru) é a interface primária para gerenciar nós, identidades e plasmídeos.

1. Comandos de Nó

2. Comandos de Identidade

3. Comandos de Plasmídeo

4. Variáveis de Ambiente

5. Veja também

• Guia · Forge CLI
• BC API
• Dicionário

🧬 DSL de Plasmídeos

A DSL (Domain Specific Language) do PAEBIRU permite definir lógica de governança e computação de forma declarativa, que é então compilada para WebAssembly (WASM).

1. Estrutura do Arquivo (.toml / .hcl)

Um plasmídeo é definido por metadados e comportamentos:

[plasmid]
name = "meu-contrato"
version = "1.0.0"

[behavior]
on_init = "state.count = 0"
on_message = """
    if message.type == "increment" {
        state.count += 1
    }
"""

2. Tipos de Dados Suportados

• Inteiros: i32, i64, u32, u64.
• Decimais: f32, f64.
• Booleanos: bool.
• Coleções: Map, List (mapeados para heapless no WASM).

3. APIs Disponíveis (Host Calls)

O plasmídeo interage com o nó através de funções seguras:

• log::info(msg): Emite logs para o nó host.
• network::send(target, msg): Envia mensagens para outros nós.
• storage::get(key): Recupera estado persistente do C.A.P.I.B.A.
• entropy::now(): Obtém o Langevin Tick atual.

4. Segurança e Restrições

• Determinismo: Plasmídeos não podem acessar o tempo do sistema ou números aleatórios não-determinísticos.
• Gas/Metering: Cada instrução WASM consome créditos no LandauerLedger.
• Isolamento: Não há acesso ao sistema de arquivos ou rede direta (apenas via host calls).

5. Veja também

• BC Plasmídeos
• Referência · WASI-PAEBIRU ABI
• Guia · Primeiro Plasmídeo

📜 HCL (HashiCorp Configuration Language)

O PAEBIRU utiliza HCL como uma alternativa ao TOML para a definição de plasmídeos complexos e orquestração de infraestrutura de névoa.

1. Por que HCL?

HCL oferece maior flexibilidade para configurações hierárquicas e suporte nativo a interpolação de variáveis, o que é útil para definir comportamentos de plasmídeos que dependem de condições de hardware específicas.

2. Exemplo de Definição de Nó

node "edge-01" {
  storage_path = "/var/lib/paebiru"
  api_port     = 1975

  sensor "temperature" {
    threshold_pain = 75.5
  }
}

plasmid "monitor" {
  version = "1.2.0"
  capabilities = ["network", "storage"]
}

3. Veja também

• Referência · DSL
• Guia · Forge CLI

🔌 WASI-PAEBIRU ABI

A ABI (Application Binary Interface) define o contrato de baixo nível entre o host (nó PAEBIRU) e o guest (módulo WASM/Plasmídeo). Ela estende o padrão WASI para suportar as necessidades específicas de sistemas distribuídos soberanos.

1. Convenções de Memória

• Linear Memory: O guest e o host compartilham um buffer de memória linear.
• Opaque Handles: Referências a recursos complexos (canais de rede, instâncias de banco) são passadas como handles inteiros de 32 bits.
• Zero-Copy: Estruturas grandes são passadas via ponteiro e tamanho, evitando serialização pesada (Dogma 4).

2. Importações de Host (Host Imports)

Funções que o módulo WASM pode invocar:

#![allow(unused)]
fn main() {
// Exemplo de assinatura na Camada 9
extern "C" {
    fn paebiru_send_message(target_ptr: *const u8, msg_ptr: *const u8, msg_len: usize) -> i32;
    fn paebiru_get_causal_tick() -> u64;
    fn paebiru_log_event(level: i32, msg_ptr: *const u8, msg_len: usize);
}
}

3. Exportações de Guest (Guest Exports)

Funções que o nó host invoca no plasmídeo:

• paebiru_init(): Chamada ao carregar o plasmídeo.
• paebiru_process_message(sender_id, msg_id): Chamada para reagir a estímulos da malha.
• paebiru_shutdown(): Chamada antes de descarregar o módulo.

4. Tratamento de Erros

A ABI utiliza códigos de retorno inteiros:

• 0: Sucesso.
• < 0: Erros de sistema (ex: -1 = Out of Memory, -2 = Permission Denied).
• > 0: Erros específicos do domínio do plasmídeo.

5. Veja também

• Dogma 4 · Interoperabilidade
• BC Plasmídeos
• Referência · DSL

🔌 SDKs e bindings

O PAEBIRU é escrito em Rust, mas é interoperável com 13 linguagens via bindings canônicos. Esta trilha documenta o design assíncrono comum e cada binding individualmente.

Princípios

• Opaque handles + zero-copy — nenhum binding expõe tipos internos do Kernel; serialização pesada é evitada na Camada 9 (tópico em formalização).
• API síncrona-para-async — bindings para linguagens síncronas (C, PHP, R, Lua) expõem wrappers que internamente despacham para o runtime tokio via thread pool.
• Capacidades, não tipos — o binding expõe capabilities (ler, assinar, votar), não structs internos.

Visão geral

Não use bindings em produção durante a Fase 1 — apenas paebiru-c é considerado estável, e mesmo assim em modo “laboratório”.

Páginas

• Design assíncrono — como o runtime tokio aparece em cada linguagem.
• Guia de release — versionamento e compatibilidade.
• Bindings individuais — um arquivo por linguagem.

Veja também

• WASI-PAEBIRU ABI — o contrato subjacente que todo binding respeita.
• Zero-Copy FFI — tópico em formalização.
• Dogma 4 · Interoperabilidade Blindada.

🌀 Design Assíncrono

O PAEBIRU é assíncrono por natureza. Este documento descreve como o modelo de concorrência do Rust (Tokio) é mapeado para as diferentes linguagens suportadas.

1. O Loop de Eventos do Kernel

Toda instância do PAEBIRU roda um runtime Tokio internamente. Mesmo em linguagens síncronas, as operações de rede e IO ocorrem em threads de background geridas pelo Rust.

2. Mapeamento por Linguagem

Linguagens Modernas (Async-Native)

• Rust/Python/TS/Go/Dart/Swift/C#: O SDK expõe funções async ou que retornam Promises/Futures. O runtime da linguagem aguarda o sinal do kernel Rust.

Linguagens Síncronas (Thread-Based)

• C/PHP/Ruby/Lua/R: O SDK fornece chamadas bloqueantes que, por baixo dos panos, despacham a tarefa para o runtime Rust e aguardam a conclusão via variável de condição (CondVar) ou polling.

3. Callbacks e Eventos

As mensagens vindas da malha (GossipSub) são entregues através de um sistema de subscrição:

1. O usuário registra um handler no SDK.
2. O Kernel Rust recebe a mensagem e a coloca em uma fila de despacho.
3. O SDK “puxa” a mensagem ou invoca o callback no contexto da linguagem alvo.

4. Veja também

• Qualidade · Dogma 2
• BC Kernel
• Referência · ABI

📦 Guia de Release

Políticas de versionamento, estabilidade e compatibilidade para os SDKs e Bindings do PAEBIRU.

1. Versionamento Semântico (SemVer)

Seguimos rigorosamente o SemVer 2.0.0 para todos os crates e pacotes de linguagem:

• Major: Quebra de compatibilidade na ABI ou APIs públicas.
• Minor: Novas funcionalidades compatíveis.
• Patch: Correções de bugs e segurança.

2. Matriz de Estabilidade

3. Política de Depreciação

Mudanças que quebram a API devem passar por um ciclo de depreciação de pelo menos uma versão Minor, emitindo warnings em tempo de compilação ou execução antes da remoção final.

4. Ciclo de Publicação

As releases dos SDKs são sincronizadas com as tags do repositório principal. O pipeline de CI automatiza a publicação para os gestores de pacotes (PyPI, npm, Maven, etc.) assim que uma tag v* é criada.

5. Veja também

• Mapeamento do Workspace
• Roadmap
• CONTRIBUTING.md

🔌 C (paebiru-c)

O binding C é a base de todos os outros 24 bindings do PAEBIRU. Cada binding — seja Java via JNI, C# via P/Invoke, Python via PyO3, ou Zig via @cImport — consome paebiru-c como contrato canônico da API do Kernel. Manter este header estável, documentado e ABI-compatível é a maior responsabilidade do projeto: qualquer quebra aqui quebra todos os 24 outros bindings simultaneamente.

O binding usa C puro (C11+) com extern "C" guards para compatibilidade com C++, segue convenções POSIX/Linux-friendly (size_t, ssize_t, uint32_t), e implementa o Dogma 4 · Opaque Handles & Zero-Copy — sem serialização JSON em hot-path, com ponteiros opacos (paebiru_node_t*), ownership explícito (caller chama _destroy), e zero-cópia via ponteiro direto para buffers do chamador.

⚠️ Status atual (v0.0.2-0): apenas o crate paebiru-kernel está implementado. Os demais bindings são esqueleto (stubs TOML + manifest) e serão preenchidos em fases posteriores do roadmap.

1. Princípios de Design

• Opaque Handles via forward-declared structs: instâncias nativas (nó, identidade, recibo) são representadas como typedef struct paebiru_node_s paebiru_node_t; com apenas forward declaration no header público — o layout interno fica escondido na .so/.a. O usuário sempre passa paebiru_node_t* (ponteiro opaco) entre funções.
• Convenção de nomenclatura:
  • Todas as funções e tipos começam com paebiru_ para evitar poluição de namespace global.
  • Funções em snake_case (paebiru_node_create, paebiru_node_send_message).
  • Tipos em snake_case com sufixo _t (paebiru_node_t, paebiru_receipt_t) — convenção POSIX.
  • Erros em paebiru_error_t enum ou retornando int (negativo em erro, 0 em sucesso) — int é mais simples para ABI stability.
  • Macros e constantes em UPPER_SNAKE_CASE com prefixo PAEBIRU_ (PAEBIRU_DEFAULT_PORT, PAEBIRU_MAX_PLASMID_SIZE).
• Gerenciamento de memória — ownership explícito: o caller é responsável por destruir os handles criados (paebiru_node_destroy(handle)). Não há garbage collection, reference counting, ou cleanup implícito. Lifespan contracts estão documentados em cada função.
• Distribuição: libpaebiru.so (Linux) / .dylib (macOS) / .dll (Windows) — empacotada via pkg-config, vcpkg, Conan, ou como target CMake find_package(paebiru). Header paebiru.h em /usr/local/include/paebiru/.
• ABI compatibility: o header segue o Itanium C++ ABI (também usado por Itanium/System V para C). Funções decoradas com __attribute__((visibility("default"))) em GCC/Clang; equivalentes MSVC via __declspec(dllexport).
• Thread-safety: o Node é thread-safe para operações de leitura (paebiru_node_send_message, _poll_event), mas não para lifecycle (_create/_destroy devem ser chamados de uma única thread).
• Zero-cópia via ponteiro direto: o caller passa const uint8_t* payload, size_t payload_len — o lado C não copia o buffer (a menos que precise). O caller deve garantir que o buffer vive durante a chamada.
• Compatibilidade C++: #ifdef __cplusplus extern "C" { guard em torno de toda a API, permitindo que C++ consuma sem name mangling.
• Determinismo temporal: funções críticas têm bound determinístico (ex: paebiru_node_poll_event retorna em ≤ 100 µs).
• Atomicidade: paebiru_node_send_message é atômico — ou retorna recibo com sucesso, ou retorna erro sem efeito colateral.

2. Instalação

Via package manager do sistema

# Debian/Ubuntu
apt-get install libpaebiru-dev

# macOS
brew install paebiru

# Arch
pacman -S paebiru

# Windows (vcpkg)
vcpkg install paebiru:x64-windows

Via CMake find_package

# CMakeLists.txt
cmake_minimum_required(VERSION 3.20)
project(my_paebiru_app LANGUAGES C CXX)

find_package(paebiru 0.1 REQUIRED PATHS /usr/local/lib/cmake/paebiru)

add_executable(myapp main.c)
target_link_libraries(myapp PRIVATE paebiru::paebiru)

cmake -B build -DPAEBIRU_DIR=/usr/local
cmake --build build
./build/myapp

Via pkg-config

pkg-config --cflags --libs paebiru
# → -I/usr/local/include -L/usr/local/lib -lpaebiru

gcc main.c $(pkg-config --cflags --libs paebiru) -o myapp

Compilação manual (a partir do source)

git clone https://github.com/paebiru/paebiru-c.git
cd paebiru-c
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make
sudo make install

Verificação

#include <paebiru.h>
#include <stdio.h>

int main(void) {
    printf("paebiru-c %d.%d.%d\n",
           paebiru_VERSION_MAJOR,
           paebiru_VERSION_MINOR,
           paebiru_VERSION_PATCH);
    return 0;
}

gcc -o check_paebiru check_paebiru.c $(pkg-config --cflags --libs paebiru)
./check_paebiru
# → paebiru-c 0.1.0

Dependências runtime

• C11+ compiler: GCC ≥ 9, Clang ≥ 10, MSVC ≥ 2019
• libc (sempre disponível)
• libpthread (para threading) — linkado automaticamente
• libdl (Linux, para dlopen/dlsym se necessário)
• Sistema: libpaebiru.so / .dylib / .dll

3. Header paebiru.h — Contrato Completo

/* include/paebiru/paebiru.h
 *
 * Header público do binding C do PAEBIRU.
 * Este é o CONTRATO CANÔNICO consumido por todos os outros
 * 24 bindings do projeto. Mudanças aqui são breaking changes
 * para todos os bindings.
 *
 * Standard: C11 + GNU extensions (GCC/Clang) ou MSVC extensions
 * License: AGPL-3.0-or-later
 */

#ifndef PAEBIRU_H
#define PAEBIRU_H

#include <stddef.h>     /* size_t, NULL */
#include <stdint.h>     /* uint8_t, uint32_t, uint64_t, int32_t */
#include <stdbool.h>    /* bool, true, false */
#include <sys/types.h>  /* ssize_t (POSIX) */

#ifdef __cplusplus
extern "C" {
#endif

/* =================================================================
 * Versioning
 * ================================================================= */

#define PAEBIRU_VERSION_MAJOR 0
#define PAEBIRU_VERSION_MINOR 1
#define PAEBIRU_VERSION_PATCH 0

/* Compile-time version check (use in application code) */
#if defined(PAEBIRU_REQUIRE_VERSION)
  #if (PAEBIRU_VERSION_MAJOR << 16 | PAEBIRU_VERSION_MINOR << 8 | \
       PAEBIRU_VERSION_PATCH) < PAEBIRU_REQUIRE_VERSION
    #error "paebiru-c version too old; please upgrade"
  #endif
#endif

/* Runtime version (callers can check API compatibility) */
const char* paebiru_version_string(void);
uint32_t paebiru_version_compat(void);  /* 0x00MMmmpp */

/* =================================================================
 * Error codes (returned by all paebiru_* functions)
 * ================================================================= */

typedef enum paebiru_error_e {
    PAEBIRU_OK              =  0,  /* Success */
    PAEBIRU_ERR_INVALID_ARG = -1,  /* Invalid argument */
    PAEBIRU_ERR_OUT_OF_MEMORY = -2,/* malloc/realloc failed */
    PAEBIRU_ERR_NETWORK     = -3,  /* Network error */
    PAEBIRU_ERR_IO          = -4,  /* File I/O error */
    PAEBIRU_ERR_TIMEOUT     = -5,  /* Operation timed out */
    PAEBIRU_ERR_NOT_FOUND   = -6,  /* Resource not found */
    PAEBIRU_ERR_ALREADY     = -7,  /* Already initialized */
    PAEBIRU_ERR_INTERNAL    = -100 /* Internal error (likely bug) */
} paebiru_error_t;

/* Returns human-readable description of an error code */
const char* paebiru_error_str(paebiru_error_t err);

/* =================================================================
 * Opaque types (forward-declared; layout is private)
 * ================================================================= */

typedef struct paebiru_node_s     paebiru_node_t;      /* Opaque node handle */
typedef struct paebiru_identity_s paebiru_identity_t;  /* Opaque identity */
typedef struct paebiru_receipt_s  paebiru_receipt_t;   /* Opaque receipt */
typedef struct paebiru_plasmid_s  paebiru_plasmid_t;   /* Opaque plasmid */
typedef struct paebiru_mesh_event_s paebiru_mesh_event_t; /* Opaque mesh event */

/* =================================================================
 * Constants
 * ================================================================= */

#define PAEBIRU_DEFAULT_PORT     1975
#define PAEBIRU_DEFAULT_PORT_STR "1975"

#define PAEBIRU_MAX_PEER_ID_LEN  128
#define PAEBIRU_MAX_CID_BYTES    32      /* BLAKE3 hash size */
#define PAEBIRU_MAX_CID_HEX_LEN  64      /* 2 * MAX_CID_BYTES, no null */
#define PAEBIRU_MAX_PAYLOAD_SIZE (16 * 1024 * 1024)  /* 16 MB */
#define PAEBIRU_MAX_PLASMID_SIZE (8 * 1024 * 1024)   /* 8 MB */

/* Event types (for paebiru_mesh_event_t) */
typedef enum paebiru_event_type_e {
    PAEBIRU_EVENT_NONE              = 0,
    PAEBIRU_EVENT_PEER_CONNECTED    = 1,
    PAEBIRU_EVENT_PEER_LOST         = 2,
    PAEBIRU_EVENT_RECEIPT_PRODUCED  = 3,
    PAEBIRU_EVENT_ALGEDONIC         = 4
} paebiru_event_type_t;

/* =================================================================
 * Node lifecycle
 * ================================================================= */

/* Create a new PAEBIRU node.
 *
 * @param storage_path  Directory for node storage (must exist, writable).
 * @return              Opaque handle on success, NULL on error.
 * @error               PAEBIRU_ERR_INVALID_ARG, PAEBIRU_ERR_OUT_OF_MEMORY
 *
 * @lifespan            Handle must be destroyed via paebiru_node_destroy.
 * @thread-safety       NOT thread-safe; call from a single thread.
 */
paebiru_node_t* paebiru_node_create(const char* storage_path);

/* Start the node (begins network discovery, listening, etc.).
 *
 * @param node          Handle from paebiru_node_create.
 * @return              PAEBIRU_OK on success, negative on error.
 * @error               PAEBIRU_ERR_ALREADY, PAEBIRU_ERR_NETWORK
 *
 * @lifespan            Until paebiru_node_stop.
 * @thread-safety       NOT thread-safe with destroy.
 */
paebiru_error_t paebiru_node_start(paebiru_node_t* node);

/* Stop the node gracefully (finishes pending operations).
 *
 * @param node          Handle.
 * @return              PAEBIRU_OK on success.
 *
 * @thread-safety       NOT thread-safe.
 */
paebiru_error_t paebiru_node_stop(paebiru_node_t* node);

/* Destroy the node and free all associated resources.
 *
 * @param node          Handle. NULL-safe (no-op if node == NULL).
 *
 * @lifespan            After this call, the handle is INVALID.
 * @thread-safety       NOT thread-safe; do not call concurrent with other ops.
 */
void paebiru_node_destroy(paebiru_node_t* node);

/* =================================================================
 * Messaging
 * ================================================================= */

/* Send a message to a target peer and wait for the Receipt.
 *
 * @param node          Handle (must be started).
 * @param target        Peer ID (null-terminated C string, max 127 chars).
 * @param target_len    strlen(target) — caller passes for zero-copy.
 * @param payload       Pointer to payload bytes (zero-copy).
 * @param payload_len   Size of payload in bytes (0 .. MAX_PAYLOAD_SIZE).
 * @param receipt_out   Output: filled with Receipt on success.
 * @return              PAEBIRU_OK on success, negative on error.
 *
 * @lifespan            payload buffer must remain valid during the call.
 *                     receipt_out is filled synchronously.
 * @thread-safety       SAFE for concurrent calls from multiple threads.
 */
paebiru_error_t paebiru_node_send_message(
    paebiru_node_t*       node,
    const char*           target,
    size_t                target_len,
    const uint8_t*        payload,
    size_t                payload_len,
    paebiru_receipt_t*    receipt_out
);

/* Send a message asynchronously (returns immediately).
 *
 * @param node          Handle.
 * @param target        Peer ID.
 * @param target_len    strlen(target).
 * @param payload       Pointer to payload (zero-copy during call).
 * @param payload_len   Size of payload.
 * @param user_data     Opaque pointer passed to completion callback.
 * @param callback      Function called with receipt (or NULL on error).
 * @return              PAEBIRU_OK if accepted; negative if queue full.
 *
 * @thread-safety       SAFE for concurrent calls.
 */
typedef void (*paebiru_send_completion_fn)(
    paebiru_error_t       status,
    paebiru_receipt_t*    receipt,
    void*                 user_data
);

paebiru_error_t paebiru_node_send_message_async(
    paebiru_node_t*             node,
    const char*                 target,
    size_t                      target_len,
    const uint8_t*              payload,
    size_t                      payload_len,
    void*                       user_data,
    paebiru_send_completion_fn  callback
);

/* =================================================================
 * Event polling
 * ================================================================= */

/* Poll for the next mesh event (non-blocking).
 *
 * @param node          Handle.
 * @param event_out     Output: filled with event data on success.
 * @return              PAEBIRU_OK if event was returned, PAEBIRU_ERR_TIMEOUT
 *                     if no event available (event_out unchanged).
 *
 * @thread-safety       SAFE for concurrent calls (one event per call).
 *                     For high-throughput, use paebiru_node_subscribe.
 */
paebiru_error_t paebiru_node_poll_event(
    paebiru_node_t*         node,
    paebiru_mesh_event_t*   event_out
);

/* Extract event type, peer ID, and payload from event. */
paebiru_event_type_t paebiru_event_get_type(const paebiru_mesh_event_t* event);
const char*          paebiru_event_get_peer_id(const paebiru_mesh_event_t* event);
size_t               paebiru_event_get_peer_id_len(const paebiru_mesh_event_t* event);
const uint8_t*       paebiru_event_get_payload(const paebiru_mesh_event_t* event);
size_t               paebiru_event_get_payload_len(const paebiru_mesh_event_t* event);
const paebiru_receipt_t* paebiru_event_get_receipt(const paebiru_mesh_event_t* event);

/* =================================================================
 * Receipt operations
 * ================================================================= */

/* Get CID (32 bytes raw). */
const uint8_t* paebiru_receipt_get_cid(const paebiru_receipt_t* receipt);

/* Get CID as 64-char lowercase hex (null-terminated, 65 bytes including NUL). */
const char* paebiru_receipt_get_cid_hex(const paebiru_receipt_t* receipt);

/* Get cost in micro-joules. */
uint64_t paebiru_receipt_get_micro_joules(const paebiru_receipt_t* receipt);

/* Get Algedonic health flag. */
bool paebiru_receipt_is_algedonically_healthy(const paebiru_receipt_t* receipt);

/* Get timestamp in nanoseconds since Unix epoch. */
uint64_t paebiru_receipt_get_timestamp_ns(const paebiru_receipt_t* receipt);

/* Compute the CausalBlock CID of arbitrary data (utility). */
paebiru_error_t paebiru_compute_cid(
    const uint8_t*  data,
    size_t          data_len,
    uint8_t         cid_out[PAEBIRU_MAX_CID_BYTES]
);

/* =================================================================
 * Status and metrics
 * ================================================================= */

typedef struct paebiru_node_status_s {
    bool        is_active;         /* started and not stopped */
    uint32_t    connected_peers;   /* count */
    uint64_t    total_messages_sent;
    uint64_t    total_messages_received;
    uint64_t    total_receipts_produced;
    double      cpu_usage_percent; /* 0.0 - 100.0 */
    double      memory_usage_mb;
} paebiru_node_status_t;

paebiru_error_t paebiru_node_get_status(
    paebiru_node_t*         node,
    paebiru_node_status_t*  status_out
);

#ifdef __cplusplus
}  /* extern "C" */
#endif

#endif /* PAEBIRU_H */

4. Exemplos Completos

Exemplo 1: Cliente síncrono

/* examples/sync_client.c */
#include <paebiru.h>
#include <stdio.h>
#include <string.h>
#include <stdlib.h>

int main(void) {
    paebiru_node_t* node = paebiru_node_create("./data");
    if (!node) {
        fprintf(stderr, "Failed to create node\n");
        return 1;
    }

    paebiru_error_t err = paebiru_node_start(node);
    if (err != PAEBIRU_OK) {
        fprintf(stderr, "Start failed: %s\n", paebiru_error_str(err));
        paebiru_node_destroy(node);
        return 1;
    }

    /* Envia mensagem */
    const char* target = "audit_mesh";
    const uint8_t payload[] = "hello from C";

    paebiru_receipt_t receipt;
    err = paebiru_node_send_message(
        node,
        target, strlen(target),
        payload, sizeof(payload) - 1,  /* exclui NUL */
        &receipt
    );
    if (err != PAEBIRU_OK) {
        fprintf(stderr, "Send failed: %s\n", paebiru_error_str(err));
    } else {
        printf("Receipt CID: %s\n", paebiru_receipt_get_cid_hex(&receipt));
        printf("Custo µJ:    %lu\n",
               (unsigned long) paebiru_receipt_get_micro_joules(&receipt));
        printf("Algedonic:   %s\n",
               paebiru_receipt_is_algedonically_healthy(&receipt) ? "OK" : "FAIL");
    }

    paebiru_node_stop(node);
    paebiru_node_destroy(node);
    return 0;
}

Exemplo 2: Polling loop multithreaded (com pthreads)

/* examples/poll_thread.c */
#define _POSIX_C_SOURCE 200809L
#include <paebiru.h>
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

typedef struct {
    paebiru_node_t* node;
    volatile int    running;
} poll_ctx_t;

static void* poll_thread(void* arg) {
    poll_ctx_t* ctx = (poll_ctx_t*)arg;
    while (ctx->running) {
        paebiru_mesh_event_t event;
        paebiru_error_t err = paebiru_node_poll_event(ctx->node, &event);
        if (err == PAEBIRU_OK) {
            const char* peer_id = paebiru_event_get_peer_id(&event);
            size_t peer_len = paebiru_event_get_peer_id_len(&event);
            printf("[event] type=%d peer=%.*s\n",
                   paebiru_event_get_type(&event),
                   (int)peer_len, peer_id);
        } else if (err == PAEBIRU_ERR_TIMEOUT) {
            usleep(10000);  /* 10 ms backoff */
        } else {
            fprintf(stderr, "Poll error: %s\n", paebiru_error_str(err));
            break;
        }
    }
    return NULL;
}

int main(void) {
    paebiru_node_t* node = paebiru_node_create("./data");
    paebiru_node_start(node);

    poll_ctx_t ctx = { .node = node, .running = 1 };
    pthread_t tid;
    pthread_create(&tid, NULL, poll_thread, &ctx);

    /* Main thread: envia mensagens */
    for (int i = 0; i < 10; i++) {
        char payload[32];
        snprintf(payload, sizeof(payload), "msg #%d", i);
        paebiru_receipt_t r;
        paebiru_node_send_message(
            node, "audit_mesh", strlen("audit_mesh"),
            (const uint8_t*)payload, strlen(payload),
            &r
        );
        sleep(1);
    }

    ctx.running = 0;
    pthread_join(tid, NULL);
    paebiru_node_destroy(node);
    return 0;
}

Exemplo 3: C++ com RAII

// examples/cpp_raii.cpp
#include <paebiru.h>
#include <iostream>
#include <stdexcept>
#include <vector>
#include <string>

class PaebiruNode {
public:
    explicit PaebiruNode(const std::string& storage_path)
        : node_(paebiru_node_create(storage_path.c_str())) {
        if (!node_) throw std::runtime_error("paebiru_node_create failed");
    }

    ~PaebiruNode() {
        if (node_) {
            paebiru_node_stop(node_);
            paebiru_node_destroy(node_);
        }
    }

    PaebiruNode(const PaebiruNode&) = delete;
    PaebiruNode& operator=(const PaebiruNode&) = delete;

    void start() {
        auto err = paebiru_node_start(node_);
        if (err != PAEBIRU_OK)
            throw std::runtime_error(std::string("start failed: ") +
                                     paebiru_error_str(err));
    }

    std::vector<uint8_t> send_message(
        const std::string& target,
        const std::vector<uint8_t>& payload
    ) {
        paebiru_receipt_t receipt;
        auto err = paebiru_node_send_message(
            node_,
            target.c_str(), target.size(),
            payload.data(), payload.size(),
            &receipt
        );
        if (err != PAEBIRU_OK) {
            throw std::runtime_error(std::string("send failed: ") +
                                     paebiru_error_str(err));
        }
        return std::vector<uint8_t>(
            paebiru_receipt_get_cid(&receipt),
            paebiru_receipt_get_cid(&receipt) + PAEBIRU_MAX_CID_BYTES
        );
    }

private:
    paebiru_node_t* node_;
};

int main() {
    try {
        PaebiruNode node("./data");
        node.start();

        std::string target = "audit_mesh";
        std::vector<uint8_t> payload{'h', 'e', 'l', 'l', 'o'};
        auto cid = node.send_message(target, payload);

        std::cout << "Receipt CID: ";
        for (auto b : cid) printf("%02x", b);
        std::cout << "\n";
    } catch (const std::exception& e) {
        std::cerr << "Error: " << e.what() << "\n";
        return 1;
    }
}

Exemplo 4: CMakeLists.txt

# CMakeLists.txt
cmake_minimum_required(VERSION 3.20)
project(my_paebiru_app LANGUAGES C CXX)

set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)
set(CMAKE_C_EXTENSIONS OFF)  # Use C11 strict, not GNU extensions

# Find paebiru-c via find_package
find_package(paebiru 0.1 REQUIRED)

add_executable(sync_client examples/sync_client.c)
target_link_libraries(sync_client PRIVATE paebiru::paebiru)

add_executable(poll_thread examples/poll_thread.c)
target_link_libraries(poll_thread PRIVATE paebiru::paebiru pthread)

# C++ example with RAII
add_executable(cpp_raii examples/cpp_raii.cpp)
target_link_libraries(cpp_raii PRIVATE paebiru::paebiru)

# Tests
enable_testing()
add_executable(test_paebiru tests/test_paebiru.c)
target_link_libraries(test_paebiru PRIVATE paebiru::paebiru)
add_test(NAME paebiru COMMAND test_paebiru)

Exemplo 5: Testes com Unity

/* tests/test_paebiru.c */
#include "unity.h"
#include <paebiru.h>
#include <string.h>

void setUp(void) {}
void tearDown(void) {}

void test_version_string_is_not_empty(void) {
    const char* v = paebiru_version_string();
    TEST_ASSERT_NOT_NULL(v);
    TEST_ASSERT_GREATER_THAN(0, strlen(v));
}

void test_version_compat_matches_macros(void) {
    uint32_t v = paebiru_version_compat();
    TEST_ASSERT_EQUAL_HEX32(
        (PAEBIRU_VERSION_MAJOR << 16) |
        (PAEBIRU_VERSION_MINOR << 8)  |
         PAEBIRU_VERSION_PATCH,
        v
    );
}

void test_error_str_returns_valid_strings(void) {
    TEST_ASSERT_EQUAL_STRING("Success", paebiru_error_str(PAEBIRU_OK));
    TEST_ASSERT_EQUAL_STRING("Invalid argument", paebiru_error_str(PAEBIRU_ERR_INVALID_ARG));
    TEST_ASSERT_EQUAL_STRING("Out of memory", paebiru_error_str(PAEBIRU_ERR_OUT_OF_MEMORY));
}

void test_node_create_with_null_path_returns_null(void) {
    paebiru_node_t* n = paebiru_node_create(NULL);
    TEST_ASSERT_NULL(n);
}

void test_node_destroy_null_is_safe(void) {
    paebiru_node_destroy(NULL);  /* não deve crashar */
}

void test_send_message_with_invalid_args_returns_error(void) {
    paebiru_node_t* n = paebiru_node_create("./data");
    TEST_ASSERT_NOT_NULL(n);
    paebiru_receipt_t r;
    /* Sem start — deve falhar */
    paebiru_error_t err = paebiru_node_send_message(
        n, "peer", 4, (const uint8_t*)"x", 1, &r
    );
    TEST_ASSERT_NOT_EQUAL(PAEBIRU_OK, err);
    paebiru_node_destroy(n);
}

int main(void) {
    UNITY_BEGIN();
    RUN_TEST(test_version_string_is_not_empty);
    RUN_TEST(test_version_compat_matches_macros);
    RUN_TEST(test_error_str_returns_valid_strings);
    RUN_TEST(test_node_create_with_null_path_returns_null);
    RUN_TEST(test_node_destroy_null_is_safe);
    RUN_TEST(test_send_message_with_invalid_args_returns_error);
    return UNITY_END();
}

5. Veja também

• WASI-PAEBIRU ABI
• Design Assíncrono
• Dogma 4 · Interoperabilidade Blindada (Zero-Copy) — diretriz arquitetural
• Binding Python (paebiru-py) — consome via PyO3
• Binding Java (paebiru-java) — consome via JNI
• Binding C# (paebiru-csharp) — consome via P/Invoke
• Binding Delphi/Object Pascal — consome via external
• Binding Ada/SPARK — consome via pragma Import
• Binding Dart (paebiru-dart) — consome via dart:ffi
• Binding Lua (paebiru-lua) — consome via mlua
• Binding PHP (paebiru-php) — consome via ext-php-rs
• Binding R (paebiru-r) — consome via extendr
• Binding Ruby (paebiru-ruby) — consome via Magnus
• Binding Swift (paebiru-swift) — consome via UniFFI
• Binding TypeScript/WASM — consome via wasm-bindgen
• Binding Zig — consome via @cImport
• Binding Elixir (paebiru-elixir) — consome via Rustler
• Binding Julia (Paebiru.jl) — consome via @ccall
• Binding COBOL — consome via CALL
• Binding Haskell (paebiru-haskell) — consome via foreign import capi
• Binding Fortran — consome via iso_c_binding
• Binding MATLAB/Octave — consome via MEX C
• Binding Prolog (paebiru-prolog) — consome via foreign/c_lib
• Binding Go (paebiru-go) — consome via cgo
• Binding Elixir (paebiru-elixir) — consome via Rustler
• BC Kernel

🟦 C++ (paebiru-cpp)

O binding C++ é, entre os 25+ do projeto, o mais fundamental depois de C — C++ é a evolução direta de C (com classes, templates, RAII, move semantics) e domina domínios onde o PAEBIRU tem presença canônica: game engines (Unreal, Unity native plugins), high-frequency trading (HFT audit com latência sub-microsegundo), computer vision (OpenCV pipelines), sistemas embarcados (ROS2, drones, robôs), desktop GUI (Qt, wxWidgets), e engenharia de sistemas (Chromium, Firefox, Office, Unreal). C++ é também a única linguagem com ecossistema maduro de coroutines, modules, concepts, ranges, expected, e span — todas as features C++20/23 que permitem modelagem type-safe e zero-overhead.

O binding usa extern "C" para vincular paebiru-c (estabelecido em PR-25), e segue o Dogma 4 · Opaque Handles & Zero-Copy — sem serialização JSON em hot-path, com RAII para cleanup determinístico (deleters customizados chamam paebiru_node_destroy), std::span<std::byte const> para zero-copy de buffers, std::expected<T, Error> (C++23) para error handling sem exceções, e coroutines (C++20) para async event streams.

⚠️ Status atual (v0.0.2-0): apenas o crate paebiru-kernel está implementado. Os demais bindings são esqueleto (stubs TOML + manifest) e serão preenchidos em fases posteriores do roadmap.

1. Princípios de Design

• Opaque Handles via std::unique_ptr<T, Deleter> com RAII: instâncias nativas (nó, identidade, recibo) são representadas por std::unique_ptr<opa::node, opa::node_deleter> com deleter customizado que chama paebiru_node_destroy no destrutor. Rule of Zero (sem destrutor custom, sem copy/move) — o smart pointer cuida de tudo.
• Convenção de nomenclatura:
  • Classes, structs, enums em PascalCase (Node, Receipt, MeshEvent, Error).
  • Funções, métodos, variáveis em snake_case (send_message, storage_path, is_healthy).
  • Constantes em kebab-case dentro de inline constexpr namespace (estilo moderno): inline constexpr auto max_cid_bytes = 32;.
  • Membros privados com sufixo _ (estilo Google/Chromium) ou prefixo m_ (estilo Qt/Boost) — documentado como escolha do projeto.
  • Namespaces: paebiru para API pública, paebiru::detail para implementação.
  • Concepts: concept MeshEventHandler para duck typing.
• Gerenciamento de memória (Rule of Zero): classes encapsulando handles C não declaram destrutor, constructor de cópia, move, ou assignment — deixam std::unique_ptr gerenciar tudo. Cleanup determinístico via RAII no escopo léxico.
• Distribuição: pacote vcpkg (Windows/Linux/macOS), Conan 2 (cross-platform), ou header-only via FetchContent no CMake. Para header-only, é o binding mais leve para embutir.
• Zero-cópia via std::span<std::byte const>: std::span é uma vista não-owning sobre memória contígua — passada para C sem cópia via reinterpret_cast<std::byte const*>. Compatível com std::vector, std::array, std::string_view, e raw pointers.
• std::expected<T, Error> para error handling (C++23): análogo a Result<T, E> em Rust. Sem exceções, sem tratamento implícito — o caller deve inspecionar o resultado. Para C++20, use tl::expected (header-only).
• Coroutines para async event streams (C++20): Generator<MeshEvent> Node::events() produz eventos via co_yield. Casa com ranges (C++20) e views (std::views::filter, std::views::take).
• Modules para organização (C++20): export module paebiru; em paebiru.cppm substitui headers tradicionais com build times mais rápidos e melhor encapsulamento.
• Concepts para type safety (C++20): template<typename T> concept Plasmable = ... permite verificação em compile-time sem SFINAE.
• Thread-safety documentado (sem std::shared_mutex por padrão — o usuário escolhe o modelo de concorrência).
• [[nodiscard]] em funções que retornam valor: previne discard acidental de Receipts, Errors, etc.
• noexcept em cleanup e observadores: marca funções que nunca lançam.

2. Instalação

Aguardando primeira publicação. Quando disponível:

Via vcpkg (recomendado)

# Instalar vcpkg
git clone https://github.com/microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh
./vcpkg/vcpkg integrate install

# Instalar paebiru
./vcpkg/vcpkg install paebiru

Via Conan 2 (cross-platform)

conan install paebiru/0.1.0@

Via CMake FetchContent (header-only)

# CMakeLists.txt
cmake_minimum_required(VERSION 3.20)
project(my_paebiru_app LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

find_package(paebiru 0.1 REQUIRED)
target_link_libraries(myapp PRIVATE paebiru::paebiru)

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/myapp

Verificação

// main.cpp
#include <paebiru/paebiru.hpp>
#include <cstdio>

int main() {
    std::printf("paebiru-cpp %d.%d\n",
                paebiru::version_major, paebiru::version_minor);
    return 0;
}

g++ -std=c++23 -o check_paebiru main.cpp -lpaebiru
./check_paebiru
# → paebiru-cpp 0

Dependências runtime

• C++23 compiler (primário): GCC ≥ 13, Clang ≥ 17, MSVC ≥ 19.36
• C++20 compiler (mínimo para coroutines + modules)
• libc (sempre disponível)
• libpthread (Linux, para std::jthread)
• libpaebiru.so/.dylib/.dll (a base C, linkada automaticamente via find_package/Conan)
• Opcional: vcpkg ou Conan (package management)

3. Exemplo de Uso

Header paebiru.hpp (a API C++ idiomática)

// include/paebiru/paebiru.hpp
#pragma once

// Inclui o header C dentro de extern "C"
extern "C" {
#include <paebiru.h>
}

#include <cstdint>
#include <cstddef>
#include <span>
#include <string_view>
#include <memory>
#include <optional>
#include <expected>  // C++23; C++20 use tl::expected
#include <variant>
#include <chrono>
#include <concepts>
#include <ranges>
#include <generator>  // C++23
#include <format>
#include <iostream>

namespace paebiru {

// =================================================================
// Constants
// =================================================================

inline constexpr std::size_t max_cid_bytes   = 32;
inline constexpr std::size_t max_cid_hex_len = 64;
inline constexpr std::size_t max_peer_id_len = 128;
inline constexpr std::uint16_t default_port  = 1975;
inline constexpr std::string_view default_port_str = "1975";

inline constexpr int version_major = PAEBIRU_VERSION_MAJOR;
inline constexpr int version_minor = PAEBIRU_VERSION_MINOR;
inline constexpr int version_patch = PAEBIRU_VERSION_PATCH;
inline constexpr std::string_view version_string = "0.1.0";

// =================================================================
// Error handling
// =================================================================

enum class error {
    ok                 = PAEBIRU_OK,
    invalid_argument   = PAEBIRU_ERR_INVALID_ARG,
    out_of_memory      = PAEBIRU_ERR_OUT_OF_MEMORY,
    network            = PAEBIRU_ERR_NETWORK,
    io                 = PAEBIRU_ERR_IO,
    timeout            = PAEBIRU_ERR_TIMEOUT,
    not_found          = PAEBIRU_ERR_NOT_FOUND,
    already            = PAEBIRU_ERR_ALREADY,
    internal           = PAEBIRU_ERR_INTERNAL,
};

[[nodiscard]]
constexpr error from_c(paebiru_error_t e) noexcept {
    return static_cast<error>(static_cast<int>(e));
}

[[nodiscard]]
inline std::string_view error_str(error e) noexcept {
    return paebiru_error_str(static_cast<paebiru_error_t>(static_cast<int>(e)));
}

template <typename T>
using result = std::expected<T, error>;

// =================================================================
// RAII Deleters
// =================================================================

namespace detail {

struct node_deleter {
    void operator()(paebiru_node_t* n) const noexcept {
        if (n) paebiru_node_destroy(n);
    }
};
struct identity_deleter {
    void operator()(paebiru_identity_t* i) const noexcept {
        if (i) paebiru_identity_destroy(i);
    }
};
struct receipt_deleter {
    void operator()(paebiru_receipt_t* r) const noexcept {
        if (r) paebiru_receipt_destroy(r);
    }
};

using node_handle     = std::unique_ptr<paebiru_node_t, node_deleter>;
using identity_handle = std::unique_ptr<paebiru_identity_t, identity_deleter>;
using receipt_handle  = std::unique_ptr<paebiru_receipt_t, receipt_deleter>;

}  // namespace detail

// =================================================================
// Receipt (POD, copyable, trivially destructible)
// =================================================================

class receipt {
public:
    std::array<std::uint8_t, max_cid_bytes> cid{};
    std::array<char, max_cid_hex_len + 1>   cid_hex{};
    std::uint64_t micro_joules  = 0;
    bool          is_healthy    = false;
    std::uint64_t timestamp_ns  = 0;

    [[nodiscard]] constexpr std::string_view cid_hex_view() const noexcept {
        return {cid_hex.data(), max_cid_hex_len};
    }
};

// =================================================================
// Mesh Event (variant of subtypes)
// =================================================================

class peer_connected_event {
public:
    std::string peer_id;
    std::chrono::system_clock::time_point timestamp;
};

class peer_lost_event {
public:
    std::string peer_id;
    std::string reason;
    std::chrono::system_clock::time_point timestamp;
};

class receipt_produced_event {
public:
    receipt receipt;
    std::chrono::system_clock::time_point timestamp;
};

using mesh_event = std::variant<
    peer_connected_event,
    peer_lost_event,
    receipt_produced_event
>;

// =================================================================
// Node (RAII wrapper)
// =================================================================

class node {
public:
    // --- Construction ---
    [[nodiscard]]
    static result<node> create(std::string_view storage_path) {
        // std::string_view → null-terminated C string
        std::string path{storage_path};  // implicit NUL terminator
        paebiru_node_t* raw = paebiru_node_create(path.c_str());
        if (!raw) {
            return std::unexpected{error::invalid_argument};
        }
        node n;
        n.handle_ = detail::node_handle{raw};
        return n;
    }

    // Rule of Zero: sem destrutor custom (unique_ptr cuida)
    // Sem copy constructor/assignment (unique_ptr é move-only)
    // Move permitido via default

    node(const node&) = delete;
    node& operator=(const node&) = delete;
    node(node&&) noexcept = default;
    node& operator=(node&&) noexcept = default;

    // --- Lifecycle ---

    [[nodiscard]]
    result<void> start() noexcept {
        auto err = paebiru_node_start(handle_.get());
        if (err != PAEBIRU_OK) {
            return std::unexpected{from_c(err)};
        }
        return {};
    }

    [[nodiscard]]
    result<void> stop() noexcept {
        auto err = paebiru_node_stop(handle_.get());
        if (err != PAEBIRU_OK) {
            return std::unexpected{from_c(err)};
        }
        return {};
    }

    // --- Messaging (zero-copy) ---

    [[nodiscard]]
    result<receipt> send_message(
        std::string_view target,
        std::span<const std::byte> payload
    ) noexcept {
        // std::string_view é não-owning; .data() não é garantido
        // NUL-terminated, então construímos string para o target.
        std::string target_str{target};
        receipt r;
        auto err = paebiru_node_send_message(
            handle_.get(),
            target_str.c_str(), target_str.size(),
            reinterpret_cast<const std::uint8_t*>(payload.data()),
            payload.size(),
            reinterpret_cast<paebiru_receipt_t*>(&r)
        );
        if (err != PAEBIRU_OK) {
            return std::unexpected{from_c(err)};
        }
        return r;
    }

    // --- Event stream (coroutine, C++20) ---

    [[nodiscard]]
    std::generator<mesh_event> events() {
        while (true) {
            paebiru_mesh_event_t raw;
            auto err = paebiru_node_poll_event(handle_.get(), &raw);
            if (err == PAEBIRU_OK) {
                co_yield convert_event(raw);
            } else if (err == PAEBIRU_ERR_TIMEOUT) {
                std::this_thread::sleep_for(std::chrono::milliseconds{10});
            } else {
                break;  // termina o generator
            }
        }
    }

    // --- Status ---

    [[nodiscard]]
    result<paebiru_node_status_t> status() const noexcept {
        paebiru_node_status_t s{};
        auto err = paebiru_node_get_status(handle_.get(), &s);
        if (err != PAEBIRU_OK) {
            return std::unexpected{from_c(err)};
        }
        return s;
    }

    // --- Accessors ---

    [[nodiscard]] paebiru_node_t* native_handle() const noexcept {
        return handle_.get();
    }

private:
    node() = default;  // para create()

    static mesh_event convert_event(const paebiru_mesh_event_t& raw) {
        switch (paebiru_event_get_type(&raw)) {
            case PAEBIRU_EVENT_PEER_CONNECTED: {
                std::string peer(paebiru_event_get_peer_id(&raw),
                                 paebiru_event_get_peer_id_len(&raw));
                return peer_connected_event{std::move(peer), std::chrono::system_clock::now()};
            }
            case PAEBIRU_EVENT_PEER_LOST: {
                std::string peer(paebiru_event_get_peer_id(&raw),
                                 paebiru_event_get_peer_id_len(&raw));
                std::string reason(reinterpret_cast<const char*>(
                                       paebiru_event_get_payload(&raw)),
                                   paebiru_event_get_payload_len(&raw));
                return peer_lost_event{std::move(peer), std::move(reason),
                                        std::chrono::system_clock::now()};
            }
            case PAEBIRU_EVENT_RECEIPT_PRODUCED: {
                const auto* raw_receipt = paebiru_event_get_receipt(&raw);
                receipt r;
                std::memcpy(r.cid.data(), paebiru_receipt_get_cid(raw_receipt),
                            max_cid_bytes);
                std::memcpy(r.cid_hex.data(),
                            paebiru_receipt_get_cid_hex(raw_receipt),
                            max_cid_hex_len);
                r.cid_hex[max_cid_hex_len] = '\0';
                r.micro_joules = paebiru_receipt_get_micro_joules(raw_receipt);
                r.is_healthy = paebiru_receipt_is_algedonically_healthy(raw_receipt);
                r.timestamp_ns = paebiru_receipt_get_timestamp_ns(raw_receipt);
                return receipt_produced_event{std::move(r),
                                              std::chrono::system_clock::now()};
            }
            default:
                std::unreachable();
        }
    }

    detail::node_handle handle_;
};

}  // namespace paebiru

Programa principal (estilo C++23 idiomático)

// examples/hello_paebiru.cpp
#include <paebiru/paebiru.hpp>
#include <print>
#include <vector>
#include <string>
#include <cstring>

int main() {
    using namespace paebiru;

    // 1. Criar nó (result<node, error>)
    auto result = node::create("./data");
    if (!result) {
        std::println(stderr, "Failed to create node: {}",
                      error_str(result.error()));
        return 1;
    }
    auto n = std::move(*result);

    // 2. Iniciar nó
    if (auto err = n.start(); !err) {
        std::println(stderr, "Failed to start: {}", error_str(err.error()));
        return 1;
    }

    // 3. Subscrever a eventos via coroutine + ranges (C++20)
    //    (em uma thread separada)
    std::jthread event_loop([&n](std::stop_token st) {
        for (const auto& event : n.events()) {
            std::visit([](const auto& e) {
                using T = std::decay_t<decltype(e)>;
                if constexpr (std::is_same_v<T, peer_connected_event>) {
                    std::println("[peer up]   {}", e.peer_id);
                } else if constexpr (std::is_same_v<T, peer_lost_event>) {
                    std::println("[peer down] {} ({})", e.peer_id, e.reason);
                } else if constexpr (std::is_same_v<T, receipt_produced_event>) {
                    std::println("[receipt]   cid={} µJ={} ok={}",
                                 e.receipt.cid_hex_view(),
                                 e.receipt.micro_joules,
                                 e.receipt.is_healthy);
                }
            }, event);

            if (st.stop_requested()) break;
        }
    });

    // 4. Enviar mensagem (zero-copy via std::span)
    const char payload_text[] = "hello from C++23";
    std::span<const std::byte> payload{
        reinterpret_cast<const std::byte*>(payload_text),
        sizeof(payload_text) - 1  // exclui NUL
    };

    auto send_result = n.send_message("audit_mesh", payload);
    if (send_result) {
        std::println("Receipt CID: {}", send_result->cid_hex_view());
        std::println("Custo µJ:     {}", send_result->micro_joules);
        std::println("Algedonic OK: {}", send_result->is_healthy);
    } else {
        std::println(stderr, "Send failed: {}",
                      error_str(send_result.error()));
    }

    // 5. Aguarda Ctrl+C para shutdown graceful
    std::cin.get();
    event_loop.request_stop();
    event_loop.join();

    // 6. Stop explícito (cleanup via RAII no destrutor seria
    //    igualmente seguro; stop() é graceful).
    n.stop();
    return 0;
}

4. Integração com Unreal, OpenCV, ROS2 e Trading

Unreal Engine 5 — Plugin C++

UE5 usa C++20 + Modules. Plugin example:

// Source/PaebiruMesh/Private/PaebiruMesh.cpp
#include "PaebiruMesh.h"
#include "Async/Async.h"  // TWeakObjectPtr

void FPaebiruMeshSubsystem::Initialize(FSubsystemCollectionBase& Collection) {
    Super::Initialize(Collection);

    auto Result = paebiru::node::create(FPaths::ProjectPersistentDownloadDir() / TEXT("paebiru"));
    if (!Result) {
        UE_LOG(LogTemp, Error, TEXT("Paebiru node creation failed: %.*s"),
               paebiru::error_str(Result.error()).data());
        return;
    }
    Node = std::move(*Result);
    Node->start();

    // Subscribe em game thread
    EventThread = FRunnableThread::Create(this, TEXT("PaebiruEventThread"));
}

void FPaebiruMeshSubsystem::Tick(float DeltaTime) {
    TOptional<paebiru::receipt> LastReceipt;
    if (CurrentReceiptQueue.Dequeue(LastReceipt)) {
        OnReceipt.Broadcast(LastReceipt.GetValue());
    }
}

OpenCV + computer vision pipeline

#include <paebiru/paebiru.hpp>
#include <opencv2/core.hpp>
#include <opencv2/imgproc.hpp>
#include <opencv2/dnn.hpp>

void processCameraFeed(const std::string& camera_url,
                       paebiru::node& n) {
    cv::VideoCapture cap(camera_url);
    cv::Mat frame;
    cv::dnn::Net yolo = cv::dnn::readNet("yolov8n.onnx");

    while (cap.read(frame)) {
        // Detecção YOLO
        cv::Mat blob;
        cv::dnn::blobFromImage(frame, blob);
        yolo.setInput(blob);
        std::vector<cv::Mat> outputs;
        yolo.forward(outputs);

        // Envia detecção como CausalBlock
        std::vector<std::byte> payload(
            outputs[0].ptr<std::byte>(),
            outputs[0].ptr<std::byte>() + outputs[0].total() * outputs[0].elemSize()
        );
        auto result = n.send_message("perception_audit",
            std::span<const std::byte>{payload.data(), payload.size()});
        if (!result) {
            std::println(stderr, "Send failed: {}",
                          paebiru::error_str(result.error()));
        }
    }
}

ROS2 (Robot Operating System 2) — C++ canônico

ROS2 Humble/Iron usa C++17. Integre PAEBIRU como nó ROS2:

// paebiru_ros2_node.cpp
#include <rclcpp/rclcpp.hpp>
#include <paebiru/paebiru.hpp>

class PaebiruNode : public rclcpp::Node {
public:
    PaebiruNode() : Node("paebiru_ros2_node") {
        auto result = paebiru::node::create("/var/lib/paebiru");
        if (!result) {
            RCLCPP_ERROR(get_logger(), "Failed to create PAEBIRU node");
            throw std::runtime_error("paebiru init failed");
        }
        mesh_node_ = std::make_unique<paebiru::node>(std::move(*result));
        mesh_node_->start();

        // Subscriber ROS2 → publisher PAEBIRU
        cmd_sub_ = create_subscription<std_msgs::msg::String>(
            "cmd", 10,
            [this](const std_msgs::msg::String& msg) {
                std::span<const std::byte> payload{
                    reinterpret_cast<const std::byte*>(msg.data.data()),
                    msg.data.size()
                };
                auto result = mesh_node_->send_message("cmd_audit", payload);
                if (!result) {
                    RCLCPP_WARN(get_logger(), "PAEBIRU send failed: %.*s",
                                paebiru::error_str(result.error()).data());
                }
            });
    }

private:
    std::unique_ptr<paebiru::node> mesh_node_;
    rclcpp::Subscription<std_msgs::msg::String>::SharedPtr cmd_sub_;
};

int main(int argc, char** argv) {
    rclcpp::init(argc, argv);
    rclcpp::spin(std::make_shared<PaebiruNode>());
    rclcpp::shutdown();
    return 0;
}

High-Frequency Trading (HFT) — latência sub-microsegundo

#include <paebiru/paebiru.hpp>
#include <chrono>
#include <print>

void hft_loop(paebiru::node& n) {
    // Pre-allocate buffer uma vez (zero reallocation)
    std::array<std::byte, 1024> order_buffer;

    // Tight loop: medir latência end-to-end
    for (int i = 0; i < 1'000'000; ++i) {
        // Preenche order (omitted)
        std::size_t order_size = fill_order(order_buffer.data(), order_buffer.size());

        const auto t0 = std::chrono::high_resolution_clock::now();
        auto result = n.send_message(
            "exchange_mesh",
            std::span<const std::byte>{order_buffer.data(), order_size}
        );
        const auto t1 = std::chrono::high_resolution_clock::now();

        if (!result) {
            std::println(stderr, "Send failed: {}",
                          paebiru::error_str(result.error()));
        }

        const auto latency_ns = std::chrono::duration_cast<std::chrono::nanoseconds>(t1 - t0).count();
        if (latency_ns > 1000) {
            std::println(stderr, "ALGEDONIC: latency {} ns", latency_ns);
        }
    }
}

Qt6 GUI (event loop integration)

#include <QCoreApplication>
#include <QObject>
#include <paebiru/paebiru.hpp>

class PaebiruBridge : public QObject {
    Q_OBJECT
public:
    explicit PaebiruBridge(paebiru::node& n, QObject* parent = nullptr)
        : QObject(parent), node_(n) {
        // Polling thread usando std::jthread
        worker_ = std::jthread([this](std::stop_token st) {
            for (const auto& event : node_.events()) {
                emit eventReceived();
                if (st.stop_requested()) break;
            }
        });
    }

    ~PaebiruBridge() override {
        worker_.request_stop();
        worker_.join();
    }

signals:
    void eventReceived();

private:
    paebiru::node& node_;
    std::jthread worker_;
};

#include "main.moc"

CMakeLists.txt para projeto C++23

cmake_minimum_required(VERSION 3.20)
project(my_paebiru_cpp_app LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)  # C++23 strict, no GNU/MSVC extensions

find_package(paebiru 0.1 REQUIRED)

add_executable(hello_paebiru examples/hello_paebiru.cpp)
target_link_libraries(hello_paebiru PRIVATE paebiru::paebiru)

# HFT example: optimization
add_executable(hft_loop examples/hft_loop.cpp)
target_link_libraries(hft_loop PRIVATE paebiru::paebiru)
target_compile_options(hft_loop PRIVATE
    -O3 -march=native -flto -fno-plt
    -Wpedantic -Werror
)

# Tests com Catch2 v3
include(FetchContent)
FetchContent_Declare(Catch2 GIT_REPOSITORY https://github.com/catchorg/Catch2.git
                               GIT_TAG v3.5.0)
FetchContent_MakeAvailable(Catch2)

add_executable(test_paebiru tests/test_paebiru.cpp)
target_link_libraries(test_paebiru PRIVATE paebiru::paebiru Catch2::Catch2WithMain)

include(Catch)
catch_discover_tests(test_paebiru)

# Module C++20 (se alvo for C++20+)
if(CMAKE_CXX_STANDARD GREATER_EQUAL 20)
    target_sources(hello_paebiru PUBLIC FILE_SET paebiru_module TYPE CXX_MODULES)
endif()

Module C++20 (paebiru.cppm)

// include/paebiru/paebiru.cppm
export module paebiru;

export {
    // Constants
    inline constexpr std::size_t max_cid_bytes = 32;
    // ... outras constantes ...
}

export import <span>;
export import <string_view>;
export import <memory>;
export import <expected>;
// ... outros imports ...

export namespace paebiru {
    enum class error { /* ... */ };
    class receipt { /* ... */ };
    class node { /* ... */ };
    // ... outras classes ...
}

5. Veja também

• WASI-PAEBIRU ABI
• Design Assíncrono
• Binding C (paebiru-c) — base consumida via extern "C"
• Binding Python (paebiru-py) — equivalente scripting
• Binding Java (paebiru-java) — equivalente JVM
• Binding C# (paebiru-csharp) — equivalente .NET
• Binding Delphi/Object Pascal — equivalente enterprise
• Binding Ada/SPARK — equivalente safety-critical
• Binding Dart (paebiru-dart) — equivalente Flutter
• Binding Lua (paebiru-lua) — equivalente scripts
• Binding PHP (paebiru-php) — equivalente web
• Binding R (paebiru-r) — equivalente estatística
• Binding Ruby (paebiru-ruby) — equivalente scripting
• Binding Swift (paebiru-swift) — equivalente Apple
• Binding TypeScript/WASM — equivalente browser
• Binding Zig — outro FFI direto
• Binding Elixir (paebiru-elixir) — equivalente BEAM
• Binding Julia (Paebiru.jl) — outro FFI direto
• Binding COBOL — equivalente mainframe
• Binding Haskell (paebiru-haskell) — equivalente funcional puro
• Binding Fortran — equivalente HPC
• Binding MATLAB/Octave — equivalente numérico
• Binding Prolog (paebiru-prolog) — equivalente lógica
• Binding Go (paebiru-go) — equivalente cloud-native
• BC Kernel

🐍 Python (paebiru-py)

O binding Python é, entre os 24+ do projeto, o canônico para ciência de dados, ML/AI federado, scripting científico, e automação. Python é a lingua franca de ML (PyTorch, JAX, TensorFlow, scikit-learn, Hugging Face) e casa com PAEBIRU via FedAvg nativo sobre paebiru-learn e via integração NumPy/PyTorch zero-copy para deltas de gradient. Mais: o ecossistema Python (numpy, pandas, polars, matplotlib, jupyter, pytest, mypy) torna Python a linguagem mais produtiva para prototipagem e experimentação de mesh.

O binding usa PyO3 (a crate Rust que gera bindings Python para Rust) para expor paebiru-c (via paebiru-rust) como módulo Python nativo, e segue o Dogma 4 · Opaque Handles & Zero-Copy — sem serialização JSON em hot-path, com __init__.py strict, dataclass(frozen=True) para Receipt e MeshEvent, context managers (with) para cleanup determinístico, async/await para hot-path, e numpy.frombuffer / torch.frombuffer para zero-copy de buffers nativos.

⚠️ Status atual (v0.0.2-0): apenas o crate paebiru-kernel está implementado. Os demais bindings são esqueleto (stubs TOML + manifest) e serão preenchidos em fases posteriores do roadmap.

1. Princípios de Design

• Opaque Handles via __init__ PyO3 + __del__ cleanup: instâncias nativas (nó, identidade, recibo) são representadas como classes Python (Node, Receipt, MeshEvent) que encapsulam um c_void_p (ponteiro opaco vindo de Rust via PyO3). __del__ chama paebiru_node_destroy quando o objeto é coletado pelo GC do Python. Context managers (with Node() as node:) fornecem cleanup determinístico imediato.
• Convenção de nomenclatura:
  • Classes em PascalCase (Node, Receipt, MeshEvent).
  • Funções, métodos, variáveis em snake_case (send_message, storage_path, is_healthy).
  • Constantes em UPPER_SNAKE_CASE (DEFAULT_PORT, MAX_PLASMID_SIZE).
  • Módulos em snake_case (paebiru.mesh, paebiru.receipt).
  • Type hints obrigatórios em todo o código público (Python 3.10+ union syntax X | Y, lowercase builtins).
  • Dataclasses frozen para tipos imutáveis: @dataclass(frozen=True, slots=True) para Receipt.
• Gerenciamento de memória: classes encapsulando handles C implementam __enter__/__exit__ (context manager) para cleanup determinístico. __del__ registra cleanup automático via GC como safety net. weakref.finalize oferece cleanup mesmo com referência circular.
• Distribuição: pacote PyPI paebiru (instalação via pip install paebiru). Wheels manylinux/musllinux/macOS/ Windows via cibuildwheel. Para NumPy/PyTorch integration, extras_require: paebiru[numpy], paebiru[torch], paebiru[jax].
• Type safety: from __future__ import annotations + mypy --strict garante que a API é type-safe. Protocol classes (MeshEventHandler) para structural typing.
• Async/await: asyncio nativo para hot-path; AsyncIterator[MeshEvent] para stream de eventos via async for. Casa com aiohttp, httpx, asyncio.gather.
• Zero-cópia via NumPy/PyTorch: numpy.frombuffer para interpretar memória C como numpy.ndarray; torch.frombuffer para torch.Tensor. Ambas evitam cópia via np.ndarray.base apontando para ctypes raw.
• PEP 544 Protocols para interfaces duck-typed:

  class MeshEventHandler(Protocol):
      def __call__(self, event: MeshEvent) -> None: ...
  

• match statement (Python 3.10+) para discriminação de MeshEvent.type:

  match event:
      case PeerConnected(peer_id): ...
      case PeerLost(peer_id, reason): ...
      case ReceiptProduced(receipt): ...
  

• __repr__ explícito para debug: repr(node) mostra Node(storage_path='~/.paebiru', handle=0x...).

2. Instalação

pip install paebiru

Extras opcionais

pip install paebiru[numpy]    # + NumPy zero-copy
pip install paebiru[torch]    # + PyTorch zero-copy
pip install paebiru[jax]      # + JAX zero-copy
pip install paebiru[async]    # + asyncio support
pip install paebiru[dev]      # + pytest, mypy, ruff, black
pip install paebiru[all]      # tudo

Verificação

import paebiru
print(paebiru.__version__)

Dependências runtime

• Python ≥ 3.10 (para match, union syntax X | Y, dataclass(slots=True))
• pip ≥ 21 com suporte a wheels manylinux
• libc (sempre disponível)
• Opcional: NumPy ≥ 1.21, PyTorch ≥ 1.10, JAX ≥ 0.4
• Opcional para desenvolvimento: mypy ≥ 1.0, pytest ≥ 7, ruff (linter), black (formatter)

3. Exemplo de Uso

Definições PyO3 (lado Rust)

#![allow(unused)]
fn main() {
// paebiru-core/src/python.rs
use pyo3::prelude::*;
use pyo3::types::PyBytes;
use paebiru_c as core;

/// Binding Python via PyO3
#[pymodule]
fn paebiru(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add("__version__", env!("CARGO_PKG_VERSION"))?;
    m.add_class::<PyNode>()?;
    m.add_class::<PyReceipt>()?;
    m.add_class::<PyMeshEvent>()?;
    m.add_function(wrap_pyfunction!(py_send_message, m)?)?;
    Ok(())
}

#[pyclass(name = "Node")]
#[derive(Clone)]
pub struct PyNode {
    inner: core::Node,
}

#[pymethods]
impl PyNode {
    #[new]
    fn new(storage_path: &str) -> PyResult<Self> {
        let node = core::Node::create(storage_path)
            .map_err(|e| pyo3::exceptions::PyValueError::new_err(e.to_string()))?;
        Ok(PyNode { inner: node })
    }

    fn start(&self) -> PyResult<()> {
        self.inner.start()
            .map_err(|e| pyo3::exceptions::PyRuntimeError::new_err(e.to_string()))
    }

    fn send_message<'py>(
        &self,
        py: Python<'py>,
        target_id: &str,
        payload: &'py PyBytes,
    ) -> PyResult<PyReceipt> {
        let receipt = self.inner
            .send_message(target_id, payload.as_bytes())
            .map_err(|e| pyo3::exceptions::PyRuntimeError::new_err(e.to_string()))?;
        Ok(PyReceipt { inner: receipt })
    }

    fn __enter__(slf: PyRef<Self>) -> PyRef<Self> { slf }
    fn __exit__(slf: PyRef<Self>, _exc_type: &PyAny, _exc_val: &PyAny, _exc_tb: &PyAny) -> PyResult<bool> {
        // Cleanup automático (sempre, mesmo em exceção)
        Ok(false)  // não suprime exceção
    }

    fn __repr__(&self) -> String {
        format!("Node(storage_path={:?})", self.inner.storage_path())
    }

    fn __del__(&mut self) {
        // Safety net: cleanup se __exit__ não foi chamado
        let _ = self.inner.destroy();
    }
}
}

Tipos Python (dataclasses frozen + slots)

# paebiru/types.py
from __future__ import annotations

from dataclasses import dataclass, field
from enum import Enum, auto
from typing import NewType, final
import numpy as np
from numpy.typing import NDArray

PeerId = NewType("PeerId", str)


class EventType(Enum):
    """Tipo discriminado de MeshEvent."""
    PEER_CONNECTED = auto()
    PEER_LOST = auto()
    RECEIPT_PRODUCED = auto()


@final
@dataclass(frozen=True, slots=True)
class Receipt:
    """Recibo Soberano (imutável, hashable)."""
    cid: bytes                   # 32 bytes raw
    cid_hex: str                 # 64 chars hex
    micro_joules: int
    is_healthy: bool

    def __post_init__(self) -> None:
        if len(self.cid) != 32:
            raise ValueError(f"cid must be 32 bytes, got {len(self.cid)}")
        if len(self.cid_hex) != 64:
            raise ValueError(f"cid_hex must be 64 chars, got {len(self.cid_hex)}")
        if self.micro_joules < 0:
            raise ValueError(f"micro_joules must be non-negative")

    def __repr__(self) -> str:
        return (
            f"Receipt(cid_hex='{self.cid_hex[:16]}...', "
            f"µJ={self.micro_joules}, healthy={self.is_healthy})"
        )


@final
@dataclass(frozen=True, slots=True)
class MeshEvent:
    """Evento da malha (imutável)."""
    type: EventType
    peer_id: PeerId
    timestamp_ns: int  # nanoseconds since epoch
    receipt: Receipt | None = None  # populado se type == RECEIPT_PRODUCED

    def __post_init__(self) -> None:
        if self.type == EventType.RECEIPT_PRODUCED and self.receipt is None:
            raise ValueError("RECEIPT_PRODUCED event must have receipt")
        if self.type != EventType.RECEIPT_PRODUCED and self.receipt is not None:
            raise ValueError("Only RECEIPT_PRODUCED event should have receipt")

    def __repr__(self) -> str:
        return f"MeshEvent({self.type.name}, peer_id={self.peer_id!r})"

Classe Node com context manager, async, e numpy

# paebiru/node.py
from __future__ import annotations

import asyncio
import contextlib
import logging
import time
from collections.abc import AsyncIterator, Callable
from typing import Protocol, final

import numpy as np
from numpy.typing import NDArray

from paebiru._native import (
    Node as _NativeNode,
    send_message as _native_send_message,
    PAEBIRU_DEFAULT_PORT,
)
from paebiru.types import MeshEvent, Receipt, EventType, PeerId

logger = logging.getLogger(__name__)


class MeshEventHandler(Protocol):
    """Protocol duck-typed para callbacks de eventos."""
    def __call__(self, event: MeshEvent) -> None: ...


@final
class Node:
    """Cliente do nó PAEBIRU.

    Exemplo:
        with Node(storage_path="~/.paebiru") as node:
            node.start()
            receipt = node.send_message("audit_mesh", b"hello")
            print(receipt)
    """

    def __init__(
        self,
        storage_path: str,
        *,
        listen_port: int = PAEBIRU_DEFAULT_PORT,
    ) -> None:
        self._storage_path = storage_path
        self._listen_port = listen_port
        self._native = _NativeNode(storage_path)
        self._started = False
        self._closed = False
        self._event_handlers: list[MeshEventHandler] = []

    def start(self) -> None:
        """Inicia o nó (síncrono, bloqueia até estar pronto)."""
        if self._started:
            return
        self._native.start()
        self._started = True
        logger.info("PAEBIRU node started at %s", self._storage_path)

    def stop(self) -> None:
        """Para o nó gracefully."""
        if not self._started or self._closed:
            return
        self._native.stop()
        self._started = False
        logger.info("PAEBIRU node stopped")

    def send_message(
        self,
        target: str,
        payload: bytes | NDArray[np.uint8] | memoryview,
    ) -> Receipt:
        """Envia mensagem síncrona e retorna Recibo Soberano."""
        if not self._started:
            raise RuntimeError("Node not started; call .start() first")
        # Zero-copy para numpy/memoryview: usa memoryview.tobytes()
        # apenas se necessário; caso contrário, passa direto.
        if isinstance(payload, np.ndarray):
            payload = memoryview(payload).cast("B")  # zero-copy
        elif isinstance(payload, memoryview):
            payload = payload.cast("B")
        return _native_send_message(
            self._native,
            target,
            bytes(payload),  # segura cópia
        )

    def send_message_async(
        self,
        target: str,
        payload: bytes,
    ) -> asyncio.Future[Receipt]:
        """Envia mensagem assíncrona via asyncio.Future."""
        return asyncio.get_event_loop().run_in_executor(
            None, self.send_message, target, payload
        )

    async def events(self) -> AsyncIterator[MeshEvent]:
        """Async iterator de eventos da malha."""
        loop = asyncio.get_event_loop()
        while not self._closed:
            event = await loop.run_in_executor(None, self._native.poll_event)
            if event is not None:
                yield event

    def subscribe(self, handler: MeshEventHandler) -> Callable[[], None]:
        """Subscreve um handler para eventos. Retorna callable de unsub."""
        self._event_handlers.append(handler)
        return lambda: self._event_handlers.remove(handler)

    # --- context manager ---

    def __enter__(self) -> Node:
        return self

    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
        self.stop()

    def __del__(self) -> None:
        try:
            self.stop()
        except Exception:  # noqa: BLE001
            pass  # GC safety net

    def __repr__(self) -> str:
        return (
            f"Node(storage_path={self._storage_path!r}, "
            f"started={self._started}, closed={self._closed})"
        )

Programa principal (estilo Python idiomático)

# examples/hello_paebiru.py
from __future__ import annotations

import asyncio
import logging

from paebiru import Node, MeshEvent, EventType

logging.basicConfig(level=logging.INFO)


def on_mesh_event(event: MeshEvent) -> None:
    """Handler para eventos de malha."""
    match event:
        case MeshEvent(type=EventType.PEER_CONNECTED, peer_id=peer_id):
            print(f"[peer up]   {peer_id}")
        case MeshEvent(type=EventType.PEER_LOST, peer_id=peer_id):
            print(f"[peer down] {peer_id}")
        case MeshEvent(type=EventType.RECEIPT_PRODUCED, receipt=receipt):
            print(f"[receipt]   {receipt}")


def main_sync() -> None:
    """Versão síncrona com context manager."""
    with Node(storage_path="~/.paebiru") as node:
        node.start()

        # Subscreve handler
        unsubscribe = node.subscribe(on_mesh_event)

        # Envia mensagem
        receipt = node.send_message("audit_mesh", b"hello from python")
        print(f"Receipt CID: {receipt.cid_hex}")
        print(f"Custo µJ:     {receipt.micro_joules}")
        print(f"Algedonic OK: {receipt.is_healthy}")

        unsubscribe()  # cleanup explícito do handler


async def main_async() -> None:
    """Versão async com async iterator."""
    with Node(storage_path="~/.paebiru") as node:
        node.start()

        # Async send
        receipt_future = node.send_message_async("audit_mesh", b"hello")
        receipt = await receipt_future
        print(f"Async receipt: {receipt.cid_hex}")

        # Async event stream
        async for event in node.events():
            print(f"Async event: {event}")


if __name__ == "__main__":
    main_sync()
    asyncio.run(main_async())

4. Integração com NumPy, PyTorch, pytest e cibuildwheel

NumPy zero-copy para FedAvg

# examples/fedavg_numpy.py
from __future__ import annotations

import numpy as np
from numpy.typing import NDArray

from paebiru import Node

def compute_local_delta(
    global_weights: NDArray[np.float32],
    local_data: NDArray[np.float32],
) -> NDArray[np.float32]:
    """Computa weight delta local (placeholder)."""
    # ... lógica real de FedAvg aqui ...
    return local_data - global_weights  # simplificado

def main() -> None:
    # Carrega pesos globais do BC de Aprendizado
    global_weights: NDArray[np.float32] = np.load("global.npy")
    local_data: NDArray[np.float32] = np.load("local.npy")

    # Computa delta como array NumPy
    delta = compute_local_delta(global_weights, local_data)

    with Node(storage_path="~/.paebiru") as node:
        node.start()
        # Zero-copy: NumPy → memoryview → C
        delta_bytes = memoryview(delta).cast("B")
        receipt = node.send_message(
            "coordinator_peer",
            delta_bytes,  # zero-copy até a fronteira FFI
        )
        print(f"Delta sent: {delta.nbytes} bytes, receipt {receipt.cid_hex}")

PyTorch zero-copy

# examples/fedavg_torch.py
from __future__ import annotations

import torch
from paebiru import Node

def main() -> None:
    # Modelo local (PyTorch)
    local_weights = {k: torch.randn(1000, 1000) for k in ["w1", "w2", "w3"]}

    # Serializa dict de tensors para buffer contíguo (zero-copy via numpy)
    delta_bytes = b"".join(
        t.detach().numpy().tobytes() for t in local_weights.values()
    )

    with Node(storage_path="~/.paebiru") as node:
        node.start()
        receipt = node.send_message("coordinator", delta_bytes)
        print(f"Sent {len(delta_bytes)} bytes (PyTorch zero-copy)")

    # Versão ainda mais zero-copy (sem numpy intermediário):
    # use `t.untyped_storage()` (PyTorch ≥ 2.1) para acessar o
    # buffer raw e criar memoryview diretamente.

pytest (property-based testing)

# tests/test_paebiru.py
from __future__ import annotations

import pytest
from hypothesis import given, strategies as st

from paebiru import Node, MeshEvent, EventType, Receipt


def test_send_message_returns_valid_receipt(tmp_path) -> None:
    """Envia mensagem e valida estrutura do Recibo."""
    storage = tmp_path / "paebiru"
    with Node(storage_path=str(storage)) as node:
        node.start()
        receipt = node.send_message("audit_mesh", b"hello")
        assert isinstance(receipt, Receipt)
        assert len(receipt.cid) == 32
        assert len(receipt.cid_hex) == 64
        assert receipt.micro_joules >= 0
        assert isinstance(receipt.is_healthy, bool)


def test_context_manager_cleanup(tmp_path) -> None:
    """Context manager deve cleanup o handle mesmo em exceção."""
    storage = tmp_path / "paebiru"
    with pytest.raises(RuntimeError):
        with Node(storage_path=str(storage)) as node:
            node.start()
            raise RuntimeError("simulated")
    # Sem leak: handle C foi destruído via __exit__


@given(target=st.text(min_size=1, max_size=60), payload=st.binary(min_size=0, max_size=1024))
def test_send_message_property(target: str, payload: bytes) -> None:
    """Property: qualquer (target, payload) válido produz recibo."""
    with Node(storage_path="/tmp/paebiru-hypothesis") as node:
        node.start()
        receipt = node.send_message(target, payload)
        assert receipt is not None
        assert len(receipt.cid) == 32

pyproject.toml (PEP 621 + maturin para PyO3)

[build-system]
requires = ["maturin>=1.5"]
build-backend = "maturin"

[project]
name = "paebiru"
version = "0.1.0"
description = "Python binding for the PAEBIRU decentralized mesh"
readme = "README.md"
requires-python = ">=3.10"
license = {text = "AGPL-3.0-or-later"}
authors = [{name = "PAEBIRU Team", email = "team@paebiru.org"}]
keywords = ["paebiru", "p2p", "mesh", "federated-learning", "sovereign-receipts"]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "Intended Audience :: Science/Research",
    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Topic :: System :: Distributed Computing",
    "Topic :: Scientific/Engineering :: Information Analysis",
]
dependencies = []

[project.optional-dependencies]
numpy = ["numpy>=1.21"]
torch = ["torch>=1.10"]
jax = ["jax>=0.4", "jaxlib>=0.4"]
async = []  # já é stdlib
dev = [
    "pytest>=7",
    "pytest-asyncio>=0.21",
    "hypothesis>=6",
    "mypy>=1.0",
    "ruff>=0.1",
    "black>=23",
    "maturin>=1.5",
]
all = ["paebiru[numpy,torch,jax,dev]"]

[project.urls]
Homepage = "https://paebiru.org"
Documentation = "https://paebiru.org/python"
Repository = "https://github.com/paebiru/paebiru-py"
Issues = "https://github.com/paebiru/paebiru-py/issues"

[tool.maturin]
# Configuração para build com maturin (PyO3 + Rust)
binding = "PyO3"
features = ["pyo3/extension-module"]
module-name = "paebiru._native"

[tool.mypy]
python_version = "3.10"
strict = true
warn_unreachable = true
disallow_untyped_decorators = true

[tool.ruff]
line-length = 100
target-version = "py310"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP", "B", "A", "C4", "DTZ", "TID", "ICN"]

cibuildwheel (cross-platform wheels)

# pyproject.toml [tool.cibuildwheel]
[tool.cibuildwheel]
build = ["cp310-*", "cp311-*", "cp312-*"]
skip = ["*-musllinux*", "*-win32"]
archs = ["x86_64", "aarch64"]
test-requires = ["pytest>=7", "hypothesis>=6"]
test-command = "pytest {project}/tests -v"

[tool.cibuildwheel.linux]
before-build = "dnf install -y libpaebiru-devel"
environment = {PAEBIRU_LIB_DIR = "/usr/local/lib"}

[tool.cibuildwheel.macos]
environment = {MACOSX_DEPLOYMENT_TARGET = "11.0"}

[tool.cibuildwheel.windows]
before-build = "pip install delvewheel"
repair-wheel-command = "delvewheel repair -w {dest_dir} {wheel} --add-path C:\\libpaebiru"

5. Veja também

• WASI-PAEBIRU ABI
• Design Assíncrono
• Binding C (paebiru-c) — base FFI consumida via PyO3
• Binding Java (paebiru-java) — equivalente JVM
• Binding C# (paebiru-csharp) — equivalente .NET
• Binding Delphi/Object Pascal — equivalente enterprise
• Binding Ada/SPARK — equivalente safety-critical
• Binding Dart (paebiru-dart) — equivalente Flutter
• Binding Lua (paebiru-lua) — equivalente scripts
• Binding PHP (paebiru-php) — equivalente web
• Binding R (paebiru-r) — equivalente estatística
• Binding Ruby (paebiru-ruby) — equivalente scripting
• Binding Swift (paebiru-swift) — equivalente Apple
• Binding TypeScript/WASM — equivalente browser
• Binding Zig — outro FFI direto
• Binding Elixir (paebiru-elixir) — equivalente BEAM
• Binding Julia (Paebiru.jl) — outro FFI direto
• Binding COBOL — equivalente mainframe
• Binding Haskell (paebiru-haskell) — equivalente funcional puro
• Binding Fortran — equivalente HPC
• Binding MATLAB/Octave — equivalente numérico
• Binding Prolog (paebiru-prolog) — equivalente lógica
• Binding Go (paebiru-go) — equivalente cloud-native
• BC Kernel
• BC Aprendizado — FedAvg/FL

🕸️ TypeScript/WASM (paebiru-ts)

Permite rodar instâncias do PAEBIRU diretamente no navegador (dashboards de observabilidade, carteiras web, ferramentas de gossip), em Node.js (servidores, CLIs, jobs), e em runtimes alternativos como Deno, Bun e Cloudflare Workers (WASM Workers). O paebiru-c é compilado para wasm32-unknown-unknown via wasm-bindgen e exposto com tipos TypeScript gerados automaticamente, seguindo o Dogma 4 · Opaque Handles & Zero-Copy — sem serialização JSON em hot-path, com ArrayBuffer / SharedArrayBuffer para zero-copy via WASM linear memory.

⚠️ Status atual (v0.0.2-0): apenas o crate paebiru-kernel está implementado. Os demais bindings são esqueleto (stubs TOML + manifest) e serão preenchidos em fases posteriores do roadmap.

1. Princípios de Design

• Opaque Handles via number: instâncias nativas (nó, identidade, recibo) são representadas por um number (índice em uma tabela de handles do lado WASM) ou um BigInt (offset na WASM linear memory). O tipo PaebiruNode é uma classe TypeScript fina que mantém o handle em um campo private readonly #handle: number e o passa para funções WASM tipadas.
• Convenção de nomenclatura:
  • Classes e tipos em PascalCase (PaebiruNode, Receipt, MeshEvent).
  • Métodos e propriedades em camelCase (start(), sendMessage(), microJoules).
  • Constantes em UPPER_SNAKE_CASE (DEFAULT_PORT, MAX_PLASMID_SIZE).
  • Discriminated unions para variantes de eventos (type: 'peer-connected' | 'peer-lost' | 'receipt').
• Gerenciamento de memória: o PaebiruNode expõe async close(): Promise<void> (chama paebiru_node_destroy via WASM). Para cleanup automático com using (TS 5.2+): using node = await Node.init(...); — o Symbol.dispose é implementado.
• Distribuição: pacote npm @paebiru/sdk (escopo @paebiru/ reservado). Builds triplos:
  • dist/index.mjs + dist/index.cjs (ESM + CommonJS)
  • dist/browser/paebiru.wasm (binary WASM, carregado via fetch + instantiateStreaming)
  • dist/types/ (declarações .d.ts geradas)
• TypeScript strict: API é totalmente tipada; sem any em hot-path; noUncheckedIndexedAccess: true no tsconfig.json recomendado.
• Async-first: toda API pública retorna Promise<T> ou é um AsyncIterable<T>. Casas com a metáfora de eventos do Kernel GALS.
• Zero-cópia via ArrayBuffer:
  • Payloads entram/saem como Uint8Array (vista sobre ArrayBuffer).
  • Quando disponível, SharedArrayBuffer permite ao host e ao WASM compartilharem memória sem cópia (necessita COOP/COEP headers no servidor).
• WebCrypto nativo: a stack criptográfica usa crypto.subtle (WebCrypto API) no navegador — mesmo primitivos do BLAKE3, Ed25519, ML-DSA, mas aproveitando aceleração de hardware.

2. Instalação

npm install @paebiru/sdk
# ou com pnpm
pnpm add @paebiru/sdk
# ou com yarn
yarn add @paebiru/sdk

Para Deno:

import { Node } from 'npm:@paebiru/sdk';

Para Bun:

bun add @paebiru/sdk

Para Cloudflare Workers (WASM), use o pacote específico:

npm install @paebiru/sdk-workers

3. Uso no Navegador

import { Node } from '@paebiru/sdk';

const node = await Node.init({
    storage: 'indexeddb',  // ou 'opfs' (Origin Private File System)
    wasmUrl: '/paebiru.wasm',  // opcional; detecta automaticamente
});

node.on('pulse', (peer) => {
    console.log(`Pulso recebido de ${peer.id}`);
});

await node.start();

Versão TypeScript idiomática (tipos explícitos, async/await)

import {
    Node,
    Receipt,
    MeshEvent,
    PeerId,
    MeshAddress,
} from '@paebiru/sdk';

// using (TS 5.2+) — cleanup automático mesmo se 'start' lançar
{
    using node = await Node.init({ storage: 'indexeddb' });
    await node.start();

    // Subscribe a eventos com tipos
    node.on('mesh-event', (event: MeshEvent) => {
        switch (event.type) {
            case 'peer-connected':
                console.log(`peer up: ${event.peerId}`);
                break;
            case 'peer-lost':
                console.log(`peer down: ${event.peerId} (${event.reason})`);
                break;
            case 'receipt-produced':
                console.log(`receipt: ${event.receipt.cid}`);
                break;
        }
    });

    // Envia mensagem e recebe Recibo Soberano
    const target: MeshAddress = MeshAddress.parse('12D3KooW...');
    const payload: Uint8Array = new TextEncoder().encode('hello');
    const receipt: Receipt = await node.sendMessage({ target, payload });

    console.log(`Receipt CID : ${receipt.cid}`);
    console.log(`Custo µJ     : ${receipt.microJoules}`);
    console.log(`Algedonic OK : ${receipt.isAlgedonicallyHealthy}`);
}
// 'using' chama node.close() automaticamente aqui

4. Uso em Node.js, Deno e Cloudflare Workers

Node.js (≥ 20, com --experimental-wasm-modules ou 22+ nativo)

import { Node } from '@paebiru/sdk';

const node = await Node.init({
    storage: 'fs:./.paebiru',  // filesystem local
    wasmUrl: new URL('./node_modules/@paebiru/sdk/dist/paebiru.wasm',
                      import.meta.url),
});
await node.start();

// ... mesma API do navegador ...
await node.close();

Deno (>= 2.0)

import { Node } from 'npm:@paebiru/sdk';

const node = await Node.init({
    storage: `fs:${Deno.cwd()}/.paebiru`,
});
await node.start();

Bun (≥ 1.0)

import { Node } from '@paebiru/sdk';

const node = await Node.init({ storage: 'fs:./.paebiru' });
await node.start();

Cloudflare Workers (WASM, sem Node API)

// src/index.ts (Worker entrypoint)
import { Node } from '@paebiru/sdk-workers';

export interface Env {
    PAEBIRU_STORAGE: R2Bucket;  // R2 binding para storage durável
}

export default {
    async fetch(request: Request, env: Env): Promise<Response> {
        const node = await Node.init({
            storage: 'r2:' + env.PAEBIRU_STORAGE.name,
        });
        await node.start();

        // Processa requisição via node e retorna Recibo Soberano
        const receipt = await node.handleHttpRequest(request);

        return new Response(JSON.stringify(receipt, null, 2), {
            headers: { 'content-type': 'application/json' },
        });
    },
};

Configure wrangler.toml:

name = "paebiru-worker"
main = "src/index.ts"
compatibility_date = "2024-09-01"

[[r2_buckets]]
binding = "PAEBIRU_STORAGE"
bucket_name = "paebiru-storage"

5. Segurança WASM

O SDK utiliza a MacrophageVM para garantir que a execução de plasmídeos no navegador seja totalmente isolada e segura contra vazamento de dados do host. Detalhes adicionais:

• Sandbox por capability: o WASM é compilado com RUSTFLAGS="-C link-arg=-z stack-size=8388608" e roda com fuel limitado (--fuel 1000000 em wasmtime).
• Sem syscalls host: o paebiru-c não chama nada fora das APIs expostas via wasm-bindgen. Não há acesso a localStorage, fetch, ou DOM a partir do WASM — apenas via host imports declarados.
• CSP recomendado: o site hospedeiro deve servir Content-Security-Policy: default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; para que o navegador execute o WASM com a política mínima.
• COOP/COEP para SharedArrayBuffer: para zero-copy via SharedArrayBuffer, o servidor deve retornar:

  Cross-Origin-Opener-Policy: same-origin
  Cross-Origin-Embedder-Policy: require-corp
  

• Subresource Integrity (SRI): o paebiru.wasm deve ser carregado com hash SRI para evitar tampering:

  <script type="module">
    import init from '@paebiru/sdk';
    await init(fetch('/paebiru.wasm',
                     { integrity: 'sha384-...' }));
  </script>
  

6. Integração com React, SvelteKit e tRPC

React (CSR + SSR via Next.js)

'use client';
import { useEffect, useState } from 'react';
import { Node, Receipt, MeshEvent } from '@paebiru/sdk';

export function usePaebiru() {
    const [node, setNode] = useState<Node | null>(null);
    const [receipts, setReceipts] = useState<Receipt[]>([]);

    useEffect(() => {
        let cancelled = false;
        (async () => {
            const n = await Node.init({ storage: 'indexeddb' });
            if (cancelled) { await n.close(); return; }
            await n.start();

            n.on('mesh-event', (e: MeshEvent) => {
                if (e.type === 'receipt-produced') {
                    setReceipts((prev) => [...prev, e.receipt]);
                }
            });
            setNode(n);
        })();
        return () => { cancelled = true; node?.close(); };
    }, []);

    return { node, receipts };
}

SvelteKit

<script lang="ts">
  import { onMount } from 'svelte';
  import { Node, type Receipt } from '@paebiru/sdk';

  let receipts: Receipt[] = [];

  onMount(() => {
    const n = Node.init({ storage: 'indexeddb' }).then(async (n) => {
      await n.start();
      n.on('mesh-event', (e) => {
        if (e.type === 'receipt-produced') receipts = [...receipts, e.receipt];
      });
      return n;
    });

    return () => { n.then((nn) => nn.close()); };
  });
</script>

tRPC (type-safe API sobre o nó)

import { initTRPC } from '@trpc/server';
import { z } from 'zod';
import { Node, MeshAddress } from '@paebiru/sdk';

const t = initTRPC.create();
const node = await Node.init({ storage: 'fs:./.paebiru' });
await node.start();

export const appRouter = t.router({
    sendMessage: t.procedure
        .input(z.object({
            target: z.string(),
            payload: z.string(),
        }))
        .mutation(async ({ input }) => {
            const target = MeshAddress.parse(input.target);
            const payload = new TextEncoder().encode(input.payload);
            return await node.sendMessage({ target, payload });
        }),
});

7. Veja também

• WASI-PAEBIRU ABI
• BC API
• Design Assíncrono
• Binding C (paebiru-c) — base FFI compilada para WASM
• Binding Java (paebiru-java) — equivalente JVM
• Binding C# (paebiru-csharp) — equivalente .NET
• Binding Dart (paebiru-dart) — equivalente Flutter
• Binding Lua (paebiru-lua) — equivalente scripts
• Binding PHP (paebiru-php) — equivalente web server
• Binding R (paebiru-r) — equivalente estatística
• Binding Ruby (paebiru-ruby) — equivalente scripting
• Binding Swift (paebiru-swift) — equivalente Apple
• BC Kernel