binding-architecture

Architecture rules for the polyglot binding layer and the C FFI boundary — crate naming, distribution paths, ownership and null-safety invariants, error-context propagation, and async patterns. Load when designing or editing language bindings, the C ABI, cbindgen headers, or FFI type/error conversions.

Ir a la instalación

Repositorio: xberg-io/agent-conventions
Última actividad en el origen: 22 de julio de 2026 a las 15:14
Idioma detectado de SKILL.md: inglés
Estrellas: 7
Forks: 2

Opciones de instalación

De forma predeterminada está seleccionado el prompt que primero revisa el origen. Puedes cambiar a un comando directo o descargar una copia local.

Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.

Un comando directo omite el prompt de revisión. Revisa el origen antes de ejecutarlo.

npx skills add https://github.com/xberg-io/agent-conventions --skill binding-architecture

El comando permanece en una sola línea. Desplázate horizontalmente para revisarlo antes de copiarlo.

¿Prefieres una copia local? Descarga los archivos que SkillsMP tiene disponibles ahora.

Revisa los archivos de origen

Lee SKILL.md y los archivos complementarios que muestra SkillsMP antes de decidir si quieres instalarlo.

SKILL.md

Instrucciones de origen · Vista previa de solo lectura

Volver a la búsqueda Volver a la instalación

xberg-brand-and-docs

Canonical xberg.io brand, product catalog, docs-site (Astro Starlight + @xberg-io/docs-theme), alef badge, docs task commands, prose style, Google Analytics IDs, brand assets, and README-template policy. Load when writing READMEs or docs, editing docs-site config, adding the ecosystem block or alef badge, or touching brand/analytics wiring.

2026-07-31

feature-flag-conventions

The shared Cargo feature-flag naming and semantics contract across xberg-io Rust libraries — the same flag names mean the same thing everywhere (otel, mcp/mcp-http, mimalloc/jemalloc, acceleration). Load when adding, renaming, or reviewing a crate's [features], or reconciling a library's flags with the rest of the stack.

2026-07-30

tracing-conventions

The canonical contract for tracing as a first-class product observability surface across xberg-io Rust libraries and services — level semantics, span/field naming, instrumentation patterns, and how xberg-enterprise consumes library spans over OTLP. Load when adding or reviewing tracing instrumentation, designing spans/events, wiring a subscriber, or reconciling observability features.

2026-07-30

Ver todos los de este repositorio

Binding Architecture

Bindings

Bindings are minimal glue: call Rust core, convert types, convert errors — no business logic

Canonical surface: Rust core API first, C FFI ABI second, language bindings third; integrations/adapters sit outside bindings

Crate naming: {lib}-py (PyO3), {lib}-node (NAPI-RS), {lib}-rb (Magnus), {lib}-php (ext-php-rs), {lib}-wasm (wasm-bindgen), {lib}-ffi (C FFI), {lib}-jni (JNI)

Distribution paths: packages/python/ (PyPI), typescript/ (npm), ruby/ (RubyGems), php/ (Composer), go/ (Go module), java/ (Maven), csharp/ (NuGet), dart/ (pub.dev), swift/ (SwiftPM), kotlin-android/ (Maven/Gradle), r/ (CRAN/GitHub), zig/ (Zig package)

Each binding has its own language-native test suite — 80%+ coverage

Generated e2e code lives under e2e/{language}/ and is not hand-edited

Error conversion must preserve context (message + numeric code) at every FFI boundary

Async: pyo3_asyncio (Python), native #[napi] async (TS), Fiber (Ruby), block on Tokio via FFI only at sync host boundaries

FFI and language interop

Every pointer has one owner, documented with SAFETY comments

Opaque handles only — never expose Rust types directly, use #[repr(transparent)] wrappers

Null safety: check ALL pointers before use, return null + error code on failure

Allocate/free pairs: every _new() has a matching _free(), caller owns *mut

Every unsafe block has a SAFETY comment: what invariant, why it holds, what breaks if violated

Generate C headers with cbindgen — CI verifies generated headers match committed

C ABI is the stable native contract for Go, Java/JNI, C#, Dart, Swift, Kotlin Android, Zig, and R wrappers

Semantic versioning for C headers, struct layouts frozen at MAJOR.MINOR boundaries

All exported functions use #[no_mangle] extern "C"

Rust Result<T, E> → host exceptions via dedicated conversion functions at every boundary

Preserve error context across boundaries: message, numeric code (1000+), source location, cause chain