Skip to content
voiage

Versioned C ABI

The versioned C ABI is the narrow native boundary for retained bindings. The header is authoritative for declarations; the symbol and layout manifests are the release allowlists.

Version negotiation and capabilities

Section titled “Version negotiation and capabilities”
  • ABI major: 1; ABI minor: 1
  • Capability-struct version: 1
  • Capability bits include version negotiation, capability query, EVPI, and ENBS.
  • VoiageHandleV1 is an opaque process-local token; zero is null and tokens are never exposed addresses.

Exported v1 symbols

Section titled “Exported v1 symbols”
voiage_v1_abi_version
voiage_v1_capabilities
voiage_v1_enbs
voiage_v1_enbs_r
voiage_v1_evpi
voiage_v1_evpi_i32
voiage_v1_evpi_i32_r
voiage_v1_error_message
voiage_v1_handle_create
voiage_v1_handle_free

The EVPI and ENBS functions delegate to Rust numerical kernels. ENBS returns the signed difference between EVSI and non-negative research cost, including valid negative results. The enbs_r and EVPI i32_r forms provide R-compatible pointer arguments and status output, while evpi_i32 accepts signed 32-bit dimensions. These adapters do not define a separate numerical policy.

Status and error transport

Section titled “Status and error transport”

Status values are fixed-width: OK, INVALID_ARGUMENT, DIMENSION_MISMATCH, BACKEND_UNAVAILABLE, NUMERICAL_FAILURE, SERIALIZATION_FAILURE, BUFFER_TOO_SMALL, PANIC, and INTERNAL_ERROR.

voiage_v1_error_message uses caller-owned storage. A null buffer with zero capacity queries the required size, which includes the trailing NUL. No partial message is written when the buffer is too small.

Fixed-width layouts

Section titled “Fixed-width layouts”
Type Size Alignment Stable fields
VoiageAbiVersionV1 12 4 struct_size@0, abi_major@4, abi_minor@8
VoiageAbiCapabilitiesV1 16 8 struct_size@0, struct_version@4, capability_bits@8
VoiageHandleV1 8 8 opaque token
voiage_v1_status 4 4 fixed-width status

The canonical manifests are symbols.txt and layouts.txt. Bindings must run the ABI lifecycle, error, and shared numerical conformance tests before publication.