Bindings de Linguagem

Bindings multi-linguagem expõem o PAEBIRU SDK em ecossistemas além de Rust, preservando garantias de segurança (PQC), privacidade (ZK) e resiliência (GALS).

Detalhes por linguagem em crates/bindings/<lang>/README.md. Esta página é a visão de referência consolidada.

Status por linguagem

Linguagem	Tecnologia	Status	Diretório
C / C++	Opaque Handles (cbindgen)	🟢 Estável	`crates/bindings/c/`
C# / .NET 8	P/Invoke + `IDisposable`	🟢 Estável	`crates/bindings/csharp/`
Dart / Flutter	Dart FFI (iOS/Android/Linux/macOS/Windows)	🟢 Estável	`crates/bindings/dart/`
Go	cgo (feature `zk` opcional)	🟢 Estável	`crates/bindings/go/`
Java / Android / Kotlin	JNI + Gradle (AutoCloseable)	🟢 Estável	`crates/bindings/java/`
Lua 5.4	mlua (vendored ou módulo)	🟢 Estável	`crates/bindings/lua/`
PHP 8.1+	ext-php-rs	🟢 Estável	`crates/bindings/php/`
Python	PyO3 / Maturin (pip)	🟢 Estável	`crates/bindings/py/`
R	extendr (Tokio runtime local)	🟢 Estável	`crates/bindings/r/`
Ruby	Magnus / rb-sys (Bundler + Rake)	🟢 Estável	`crates/bindings/ruby/`
Swift / iOS / macOS	UniFFI / XCFramework	🟢 Estável	`crates/bindings/swift/`
TypeScript / JS	WASM via wasm-bindgen (npm/yarn)	🟢 Estável	`crates/bindings/ts/`
Zig	Zig build system + C ABI	🟡 Experimental (Novo!)	`crates/bindings/zig/`

Todos os 12 primeiros bindings são estáveis. Não há binding stub nesta lista ou em estado experimental fora dessa lista — releases seguem SDK_RELEASE_GUIDE.md.

Padrão arquitetônico — Opaque Handle & Zero-Copy

Todos os bindings (exceto WASM, que usa import/export direto) seguem o Opaque Handle Pattern e a estratégia Zero-Copy Cognitive para máxima performance:

Opaque Handle: O lado Rust expõe um handle opaco (ponteiro sem campos visíveis). O cliente da linguagem-alvo passa o handle de volta para cada operação. Isto preserva a ownership de Rust e evita que erros de memória atravessem a FFI.
Zero-Copy Cognitive: Para estados de alta frequência (Camada 9), o SDK evita a serialização JSON. As funções de consulta operam diretamente sobre o handle e retornam valores primitivos ou snapshots rápidos, minimizando alocações no heap da linguagem hospedeira.
Gerenciamento de Memória: A liberação é explícita via função paebiru_free_* correspondente.

// Exemplo de consulta cirúrgica Zero-Copy
Layer9Handle* l9 = paebiru_l9_get_handle(ctx);
double temp = paebiru_l9_get_temperature(l9); // Sem alocação/cópia
bool aligned = paebiru_l9_is_aligned(l9);      // Consulta direta
paebiru_l9_free(l9);

Wrappers idiomáticos (IDisposable em C#, AutoCloseable em Java, finalizer em Python, with-statement etc.) envolvem o ciclo new → free para o usuário final.

API comum (13 linguagens)

Toda binding implementa, no mínimo:

Operação	Equivalente Rust
`get_status()`	`PaebiruClient::get_status()`
`get_metabolism()`	`PaebiruClient::get_metabolism()`
`submit_compute_job(payload, suite?)`	`PaebiruClient::submit_compute_job(...)`
`prove_range(value, bits)` (feature `zk`)	`PaebiruZkClient::prove_range(...)`
`verify_proof(proof)` (feature `zk`)	`PaebiruZkClient::verify_proof(...)`

A API do Context (Ingest → Metabolize → Excrete) também é exposta em todos os bindings — permite escrever plasmídeos fora de Rust em linguagens com runtime WASM (TypeScript via WASM, Python via PyO3 + WASI, etc.).

Async em linguagens não-Rust

Todas as bindings que executam I/O (submit_compute_job, get_status) usam um runtime Tokio interno ao binding. Detalhes:

JS/TS — async/await nativo via WASM Promises.
Python — opção entre API sync (bloqueante) e API asyncio (via PyO3 0.21). Veja PYTHON_ASYNC_PATTERNS.md.
Swift — async/await mapeado via UniFFI.
C# / Dart / Kotlin — Task/Future nativos.
C / Go / Lua / PHP / R / Ruby / Zig — APIs síncronas; runtime Tokio bloqueia internamente.

Racional completo em ASYNC_DESIGN_RATIONALE.md.

Compilação

# Todos os bindings (faz parte do alvo Make principal)
make build

# Binding específico
rtk cargo build -p paebiru-py --release            # Python
rtk cargo build -p paebiru-ts --release            # TypeScript/WASM
rtk cargo build -p paebiru-py --no-default-features  # macOS sem extension-module

Distribuição

Binding	Canal
Python	PyPI (`pip install paebiru`)
TS/JS	npm / yarn (target browser + Node.js)
Swift	Swift Package Manager / XCFramework
Java	Maven Central (artefato Gradle)
.NET	NuGet
Dart	pub.dev
Ruby	RubyGems
Lua	LuaRocks
PHP	PECL (planejado); hoje via Composer + ext local
R	CRAN (planejado); hoje via `R CMD INSTALL`
Go	Go modules (`go get github.com/silvanoneto/paebiru/.../go`)
C / C++	`.h` + `lib*.{a,so,dylib}` distribuídos com cada release
Zig	`build.zig` + `build.zig.zon` integrando via C ABI

Veja SDK_RELEASE_GUIDE.md para o procedimento de release.

Cross-references

reference/SDK.md — referência da API Rust nativa.
sdk/ASYNC_DESIGN_RATIONALE.md — modelo async.
sdk/PYTHON_ASYNC_PATTERNS.md — workarounds Python.
sdk/SDK_RELEASE_GUIDE.md — distribuição multi-linguagem.
crates/bindings/<lang>/README.md — referências locais granulares.

Keyboard shortcuts