Contexto de Exposição: API HTTP, SDK e Forge CLI (As Janelas)

Esta camada conecta o organismo PAEBIRU ao mundo externo: expõe o estado metabólico do nó via HTTP, oferece um SDK Rust para escrita de WasmPlasmids e clientes nativos, fornece a CLI de desenvolvimento (PaebiruForgeCLI) e garante interoperabilidade de alta performance via FFI para as 13 linguagens do ecossistema.

classDiagram
    direction TB

    class ApiServer {
        <<Axum_HTTP>>
        - state: Arc~ApiState~
        + start_api_server(state)
    }

    class ApiState {
        <<Shared_Handler_State>>
        - agent: Arc~AbaporuActor~
        - home_geo: String
        - x402_middleware: X402Middleware
    }

    class StatusEndpoint {
        <<GET_/status>>
        + get_status() NodeStatus
    }

    class MetabolismEndpoint {
        <<GET_/metabolism>>
        + get_metabolism() MetabolismStats
    }

    class ComputeEndpoint {
        <<POST_/compute>>
        + handle_compute(WasmPayload) TaskReceipt
        + challenge_402() X402Challenge
        + verify_payment(JouleTransfer) bool
    }

    class X402Middleware {
        <<HTTP_402_Payment>>
        - ask_joules: u64
        - nonce: [u8 32]
        + challenge() Response402
        + verify(JouleTransfer) bool
        + settle(BarterEngine)
    }

    class NodeStatus {
        + health: String
        + peer_count: u32
        + home_geo: String
    }

    class MetabolismStats {
        + balance_joules: u128
        + pain_level: f64
    }

    class PaebiruClient {
        <<feature_client>>
        - client: reqwest::Client
        - base_url: String
        - max_joules: u64
        + get_status() Json
        + get_metabolism() Json
        + compute(wasm, input) TaskReceipt
        + handle_402(challenge) JouleTransfer
    }

    class Context {
        <<WASM_Guest_Context>>
        + emit_receipt(SovereignReceipt)
        + dissent(reason) SovereignReceipt
    }

    class PaebiruForgeCLI {
        <<DevEx_Tooling>>
        + simulateChaos(AlgedonicLevel)
        + spawnLocalLakehouse()
        + tail(node)
    }

    class FFI_Layer9 {
        <<C-ABI_RFC025>>
        + get_l9_handle() OpaqueHandle
        + get_temperature(handle) f64
        + is_aligned(handle) bool
    }

    ApiServer *-- ApiState
    ApiServer ..> StatusEndpoint : route
    ApiServer ..> MetabolismEndpoint : route
    ApiServer ..> ComputeEndpoint : route
    ApiState *-- X402Middleware
    StatusEndpoint --> NodeStatus
    MetabolismEndpoint --> MetabolismStats
    ComputeEndpoint ..> X402Middleware : payment_gate
    ComputeEndpoint ..> WasmExecutor : execute
    ApiState o-- AbaporuActor
    PaebiruClient ..> ApiServer : HTTP/JSON
    PaebiruClient ..> X402Middleware : auto_handle_402
    PaebiruForgeCLI ..> ApiServer : control plane
    FFI_Layer9 ..> AbaporuActor : zero-copy access
    Context <.. WasmPlasmid : entry point

Canais de Integração

API HTTP (Axum): Canal principal para comandos remotos, submissão de jobs CoD e observabilidade (JSON/Prometheus).
SDK Native (Rust): Primitivas para construção de plasmídeos e integração profunda em Rust.
FFI Interop (C-ABI - RFC 025): Acesso de ultra-alta performance ao estado cognitivo (Camada 9) para as 13 linguagens suportadas, utilizando Opaque Handles e Zero-Copy.
Forge CLI: Ferramental de orquestração, simulação de caos e telemetria para desenvolvedores.

Endpoints HTTP

Método	Path	Resposta	Origem dos dados
`GET`	`/status`	`NodeStatus { health, peer_count, home_geo }`	`ApiState.home_geo` + malha libp2p
`GET`	`/metabolism`	`MetabolismStats { balance_joules, pain_level }`	`AbaporuActor.get_balance()` + `AlgedonicSensor.read()`
`GET`	`/v1/layer9/granularity`	`Layer9Granularity { mode, temperature }`	`AbaporuActor` / `BiologyActor`
`POST`	`/compute`	`TaskReceipt` (após pagamento) ou `402` (desafio x402)	`WasmExecutor` via `X402Middleware`

Porta padrão: PAEBIRU_API_PORT (default 1975, ano da Antropofagia 2.0).

Fluxo x402

O endpoint /compute implementa o protocolo HTTP 402 nativo para micropagamentos M2M, conforme especificado na RFC 010 (Compute-over-Data):

Cliente                                  Compute Node (/compute)
  │                                              │
  │── POST /compute (WASM payload) ─────────────▶│
  │                                              │
  │◀── 402 Payment Required ────────────────────│
  │    X-Payment-Required:                       │
  │      scheme="paebiru-joule",                 │
  │      amount=<ask_joules>,                    │
  │      recipient=<node_id>,                    │
  │      nonce=<32-byte hex>,                    │
  │      expires=<timestamp>                     │
  │                                              │
  │  [SDK constrói JouleTransfer assinado]       │
  │                                              │
  │── POST /compute ─────────────────────────────▶│
  │    X-Payment: <base64url(JouleTransfer)>     │
  │                                              │
  │◀── 200 OK ───────────────────────────────────│
  │    TaskReceipt {                             │
  │      task_id, output_hash,                   │
  │      joules_used, signature,                 │
  │      verifier_id,                            │
  │      landauer_ledger                         │
  │    }                                         │

O PaebiruClient detecta o status 402 automaticamente, constrói e assina o JouleTransfer, e retransmite com o header X-Payment. O chamador nunca vê o ciclo — recebe direto o TaskReceipt.

SDK (`paebiru-sdk`)

Context: contexto WASM injetado em plasmídeos. Expõe emit_receipt() (excreção soberana) e dissent() (recusa argumentada, gera SovereignReceipt::Dissonance).
define_main! (macro): gera o entry point extern "C" fn run() esperado pelo WasmExecutor do contexto Economia.
PaebiruClient (feature client): cliente HTTP nativo com suporte nativo ao fluxo x402. Detecta 402, constrói JouleTransfer assinado, retransmite com X-Payment. Recusa requisição se ask_joules > max_joules configurado. Além de observabilidade, é agora o cliente oficial para CoD.

Mapeamento de Diretórios

crates/api/src/adapters/rest_server.rs — ApiServer, ApiState, handlers get_status / get_metabolism / post_compute, structs.
crates/api/src/adapters/x402.rs — X402Middleware, X402Challenge, lógica de verificação de JouleTransfer.
crates/sdk/src/lib.rs — Context, SovereignReceipt, PaebiruClient (x402-aware), macro define_main!.
apps/node/src/chaos/ — PaebiruForgeCLI (chaos, lakehouse local, observabilidade).

Referências cruzadas

O MetabolismEndpoint consome diretamente o NodeLifecycleManager documentado em BIOLOGY.md.
Plasmídeos construídos via SDK são executados pelo WasmExecutor descrito em ECONOMY.md.
O PaebiruClient não substitui o DeltaTTransport (KERNEL.md) — é apenas um canal de leitura para fora do Rizoma.
Detalhes do SDK em reference/SDK.md; detalhes do Forge CLI em reference/CLI.md.

Precificação Dinâmica via DRE

O X402Middleware consulta o DreMultiplier do contexto Economia para precificar requisições dinamicamente:

Cliente requisita /compute.
Middleware calcula ask_joules = base_cost / (1.0 + B_soc) para o cliente (subsídio social) e avalia o DreMultiplier ($\mathcal{M}$) do servidor para recompensar o provedor.
$B_{soc}$ alto do cliente → desconto (incentivo a tarefas de utilidade social).
$B_{hw}$ e $B_{en}$ altos do servidor → maior recompensa em Joules (incentivo a hardware sustentável).

Isto fecha o laço algedônico→econômico→roteamento: o preço é o sinal de saúde da malha.

Observabilidade

Prometheus em /metrics (porta padrão 1975):
- regional_pain (gauge) — getAveragePain() agregado por GeoTag, exposto para painéis de saúde da malha.
- metabolism_joules_total (counter) — débitos/créditos do BarterEngine.
- pol_verifications_total{outcome} — sucessos e falhas do Gate 4 (ZK-PoL).
- pq_signatures_verified_total{algo} — counters por algoritmo (ML-DSA/SLH-DSA).
OpenTelemetry — spans propagados desde /compute até WasmExecutor e LandauerLedger; permite traces end-to-end de um job CoD.

Endpoints Adicionais

POST /economy/swap — swap atômico Joule ↔ crédito mútuo ↔ bandwidth (três denominações da unidade econômica canônica, ver theory/workspace_mapping.md).
GET /metrics — Prometheus (acima).

Detalhes da CLI (Forge) que opera contra estes endpoints em reference/CLI.md.

Keyboard shortcuts