Module contracts 

GH-279: Kernel-Level Contracts for the Sovereign AI Stack

Defines invariants that MUST hold for ANY data entering trueno compute kernels. Consumers (realizar, aprender) validate data against these contracts BEFORE calling any kernel. Violating a contract is a hard error, not a silent default.

Contract Hierarchy

aprender (import) ──► enforce_architecture_completeness()  [tensor names]
                       │
realizar (load)   ──► contract_gate::validate_model_load()  [architecture]
                       │
trueno (kernel)   ──► contracts::validate_weight_buffer()    [bytes & layout]

This module is the bottom layer — raw buffer and layout validation. If these fail, the kernel WILL produce garbage or crash.

Structs

QuantFormat

Quantization format descriptor with block geometry.

WeightBufferError

Error returned when a weight buffer fails contract validation.

Enums

TensorLayout

Tensor layout used by all trueno kernels.

Constants

ALL_FORMATS

All supported quantization formats, ordered by GGML type ID.

Q4_0

Q4_0 block format: 32 elements, 18 bytes

Q4_1

Q4_1 block format: 32 elements, 20 bytes

Q4_K

Q4_K super-block format: 256 elements, 144 bytes (4.5 bits/weight)

Q4_K_BLOCK_BYTES

Q4_K super-block byte size

Q4_K_BLOCK_SIZE

Q4_K super-block size (elements per block)

Q5_0

Q5_0 block format: 32 elements, 22 bytes

Q5_K

Q5_K super-block format: 256 elements, 176 bytes (5.5 bits/weight)

Q5_K_BLOCK_BYTES

Q5_K super-block byte size

Q5_K_BLOCK_SIZE

Q5_K super-block size (elements per block)

Q6_K

Q6_K super-block format: 256 elements, 210 bytes (6.5 bits/weight)

Q6_K_BLOCK_BYTES

Q6_K super-block byte size

Q6_K_BLOCK_SIZE

Q6_K super-block size (elements per block)

Q8_0

Q8_0 block format: 32 elements, 34 bytes

STACK_LAYOUT

The stack-wide tensor layout. All kernels assume this.

Functions

format_by_ggml_type

Lookup a quantization format by GGML type ID.

validate_f32_buffer

Validate that an F32 weight buffer has correct element count.

validate_gemv_shapes

Validate GEMV shape invariants for row-major layout.

validate_weight_buffer

Validate a weight buffer against a known GGML type ID.