QH256 in C — A Deterministic 256-Bit State Structure for K501-AIONARC

128 cells
×
2 bits per cell
=
256 bits
=
32 bytes

UNKNOWN = 00
FALSE   = 01
TRUE    = 10
GUARD   = 11

structure != semantics

SYSTEM:        K501-AIONARC
NAMESPACE:     K501-Aionarc
DOCUMENT:      QH256 C Reference Implementation
LANGUAGE:      C11
STATUS:        CANONICAL STRUCTURE / REFERENCE IMPLEMENTATION
MODE:          DETERMINISTIC / APPEND-ONLY / NO-DRIFT
AUTHOR:        Patrick R. Miller (Iinkognit0)
ORCID:         0009-0004-3275-9545

TIME ANCHOR:
Unix Epoch:    1786954613
UTC:           2026-08-17 08:16:53 UTC
Europe/Berlin: 2026-08-17 10:16:53 CEST

QH256:
128 cells
2 bits per cell
256 bits
32 bytes

STATE ALPHABET:
UNKNOWN = 00
FALSE   = 01
TRUE    = 10
GUARD   = 11

128 × 2 = 256 bits

256 / 8 = 32 bytes

00
01
10
11

Σ = { UNKNOWN, FALSE, TRUE, GUARD }

QH256 ∈ Σ^128

QH256 ≅ B^256

B = {0,1}

4^128 = 2^256

UNKNOWN ≠ low embedding value
FALSE   ≠ negative embedding value
TRUE    ≠ positive embedding value
GUARD   ≠ quantization level

QH256 != embedding
QH256 != binary embedding
QH256 != vector quantizer
QH256 != GPU storage format

typedef struct qh256 {
    uint8_t bytes[32];
} qh256_t;

QH256
│
├── 32 bytes
│
├── 128 cells
│
└── 4 cells per byte

cell 0  -> byte 0, bits 0..1
cell 1  -> byte 0, bits 2..3
cell 2  -> byte 0, bits 4..5
cell 3  -> byte 0, bits 6..7

cell 4  -> byte 1, bits 0..1

...

cell 127 -> byte 31, bits 6..7

qh256/
├── qh256.h
├── qh256.c
└── test_qh256.c

#ifndef K501_QH256_H
#define K501_QH256_H

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * K501 QH256
 *
 * 128 cells × 2 bits = 256 bits = 32 bytes.
 *
 * Canonical states:
 *
 * UNKNOWN = 00
 * FALSE   = 01
 * TRUE    = 10
 * GUARD   = 11
 *
 * This implementation treats QH256 exclusively
 * as the defined structural state space.
 *
 * No embedding semantics.
 * No quantization semantics.
 */

#define QH256_CELL_COUNT       128u
#define QH256_BITS             256u
#define QH256_BYTES            32u
#define QH256_CELLS_PER_BYTE   4u
#define QH256_CELL_MASK        0x03u

typedef enum qh256_state {
    QH256_UNKNOWN = 0u, /* 00 */
    QH256_FALSE   = 1u, /* 01 */
    QH256_TRUE    = 2u, /* 10 */
    QH256_GUARD   = 3u  /* 11 */
} qh256_state_t;


/*
 * Exact physical structure:
 *
 * 32 bytes = 256 bits
 * 4 cells per byte
 * 2 bits per cell
 */

typedef struct qh256 {
    uint8_t bytes[QH256_BYTES];
} qh256_t;


/* ============================================================
 * Construction / Reset
 * ============================================================ */

void qh256_clear(qh256_t *q);

void qh256_fill(
    qh256_t *q,
    qh256_state_t state
);


/* ============================================================
 * Cell access
 * ============================================================ */

bool qh256_set(
    qh256_t *q,
    size_t cell_index,
    qh256_state_t state
);

bool qh256_get(
    const qh256_t *q,
    size_t cell_index,
    qh256_state_t *out_state
);


/* ============================================================
 * Validation / Comparison
 * ============================================================ */

bool qh256_state_valid(
    qh256_state_t state
);

bool qh256_is_valid(
    const qh256_t *q
);

bool qh256_equal(
    const qh256_t *a,
    const qh256_t *b
);


/* ============================================================
 * Byte representation
 * ============================================================ */

bool qh256_from_bytes(
    qh256_t *q,
    const uint8_t bytes[QH256_BYTES]
);

void qh256_to_bytes(
    const qh256_t *q,
    uint8_t bytes[QH256_BYTES]
);


/* ============================================================
 * State counting
 * ============================================================ */

void qh256_count_states(
    const qh256_t *q,
    size_t *unknown,
    size_t *false_count,
    size_t *true_count,
    size_t *guard
);


/* ============================================================
 * Deterministic text representation
 *
 * Caller requires at least 257 bytes:
 * 256 characters + '\0'
 * ============================================================ */

void qh256_to_bitstring(
    const qh256_t *q,
    char out[257]
);


/* ============================================================
 * Structural checksum
 *
 * FNV-1a 64-bit.
 *
 * Not cryptographic.
 * Only a deterministic structural checksum.
 * ============================================================ */

uint64_t qh256_fnv1a64(
    const qh256_t *q
);


#ifdef __cplusplus
}
#endif

#endif /* K501_QH256_H */

#include "qh256.h"

#include <assert.h>
#include <string.h>


#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L

_Static_assert(
    QH256_CELL_COUNT == 128u,
    "QH256 must contain exactly 128 cells"
);

_Static_assert(
    QH256_BITS == 256u,
    "QH256 must contain exactly 256 bits"
);

_Static_assert(
    QH256_BYTES == 32u,
    "QH256 must occupy exactly 32 bytes"
);

_Static_assert(
    sizeof(qh256_t) == QH256_BYTES,
    "Unexpected qh256_t size"
);

#endif


/* ============================================================
 * Internal cell addressing
 * ============================================================ */

/*
 * 1 byte = 8 bits
 * 1 cell = 2 bits
 *
 * Therefore:
 *
 * 4 cells / byte
 *
 * cell 0 -> byte 0, bits 0..1
 * cell 1 -> byte 0, bits 2..3
 * cell 2 -> byte 0, bits 4..5
 * cell 3 -> byte 0, bits 6..7
 *
 * cell 4 -> byte 1, bits 0..1
 *
 * ...
 */

static inline size_t
cell_byte_index(size_t cell_index)
{
    return cell_index >> 2;
}


static inline unsigned
cell_shift(size_t cell_index)
{
    return (unsigned)((cell_index & 3u) << 1);
}


/* ============================================================
 * State validation
 * ============================================================ */

bool
qh256_state_valid(qh256_state_t state)
{
    /*
     * All four 2-bit combinations are valid QH256 states.
     */

    return ((unsigned)state & ~3u) == 0u;
}


/* ============================================================
 * Clear QH256
 * ============================================================ */

void
qh256_clear(qh256_t *q)
{
    assert(q != NULL);

    memset(
        q->bytes,
        0,
        sizeof(q->bytes)
    );
}


/* ============================================================
 * Fill complete QH256 with one state
 * ============================================================ */

void
qh256_fill(
    qh256_t *q,
    qh256_state_t state
)
{
    uint8_t packed;

    assert(q != NULL);
    assert(qh256_state_valid(state));

    /*
     * Copy the 2-bit state into all four
     * 2-bit fields of a byte.
     */

    packed = (uint8_t)(
          (unsigned)state
        | ((unsigned)state << 2)
        | ((unsigned)state << 4)
        | ((unsigned)state << 6)
    );

    memset(
        q->bytes,
        packed,
        sizeof(q->bytes)
    );
}


/* ============================================================
 * Set single cell
 * ============================================================ */

bool
qh256_set(
    qh256_t *q,
    size_t cell_index,
    qh256_state_t state
)
{
    size_t byte_index;
    unsigned shift;
    uint8_t mask;

    if (q == NULL) {
        return false;
    }

    if (cell_index >= QH256_CELL_COUNT) {
        return false;
    }

    if (!qh256_state_valid(state)) {
        return false;
    }

    byte_index = cell_byte_index(cell_index);
    shift = cell_shift(cell_index);

    mask = (uint8_t)(
        QH256_CELL_MASK << shift
    );

    /*
     * Clear existing 2-bit field.
     */

    q->bytes[byte_index] =
        (uint8_t)(
            q->bytes[byte_index]
            & (uint8_t)~mask
        );

    /*
     * Insert new state.
     */

    q->bytes[byte_index] =
        (uint8_t)(
            q->bytes[byte_index]
            | ((uint8_t)state << shift)
        );

    return true;
}


/* ============================================================
 * Get single cell
 * ============================================================ */

bool
qh256_get(
    const qh256_t *q,
    size_t cell_index,
    qh256_state_t *out_state
)
{
    size_t byte_index;
    unsigned shift;

    if (q == NULL) {
        return false;
    }

    if (out_state == NULL) {
        return false;
    }

    if (cell_index >= QH256_CELL_COUNT) {
        return false;
    }

    byte_index = cell_byte_index(cell_index);
    shift = cell_shift(cell_index);

    *out_state =
        (qh256_state_t)(
            (q->bytes[byte_index] >> shift)
            & QH256_CELL_MASK
        );

    return true;
}


/* ============================================================
 * Structural QH256 validation
 * ============================================================ */

bool
qh256_is_valid(const qh256_t *q)
{
    /*
     * Every 2-bit combination is one of the
     * four defined QH256 states.
     *
     * Therefore no invalid bit pattern exists
     * inside the 256-bit storage structure.
     */

    return q != NULL;
}


/* ============================================================
 * Compare QH256
 * ============================================================ */

bool
qh256_equal(
    const qh256_t *a,
    const qh256_t *b
)
{
    if (a == NULL || b == NULL) {
        return false;
    }

    return memcmp(
        a->bytes,
        b->bytes,
        QH256_BYTES
    ) == 0;
}


/* ============================================================
 * Create from bytes
 * ============================================================ */

bool
qh256_from_bytes(
    qh256_t *q,
    const uint8_t bytes[QH256_BYTES]
)
{
    if (q == NULL) {
        return false;
    }

    if (bytes == NULL) {
        return false;
    }

    memcpy(
        q->bytes,
        bytes,
        QH256_BYTES
    );

    return true;
}


/* ============================================================
 * Export to bytes
 * ============================================================ */

void
qh256_to_bytes(
    const qh256_t *q,
    uint8_t bytes[QH256_BYTES]
)
{
    assert(q != NULL);
    assert(bytes != NULL);

    memcpy(
        bytes,
        q->bytes,
        QH256_BYTES
    );
}


/* ============================================================
 * Count states
 * ============================================================ */

void
qh256_count_states(
    const qh256_t *q,
    size_t *unknown,
    size_t *false_count,
    size_t *true_count,
    size_t *guard
)
{
    size_t counts[4] = {
        0,
        0,
        0,
        0
    };

    size_t i;

    assert(q != NULL);

    for (i = 0; i < QH256_CELL_COUNT; ++i) {

        qh256_state_t state;

        bool ok =
            qh256_get(
                q,
                i,
                &state
            );

        assert(ok);

        counts[(unsigned)state]++;
    }

    if (unknown != NULL) {
        *unknown =
            counts[QH256_UNKNOWN];
    }

    if (false_count != NULL) {
        *false_count =
            counts[QH256_FALSE];
    }

    if (true_count != NULL) {
        *true_count =
            counts[QH256_TRUE];
    }

    if (guard != NULL) {
        *guard =
            counts[QH256_GUARD];
    }
}


/* ============================================================
 * Deterministic 256-bit representation
 * ============================================================ */

void
qh256_to_bitstring(
    const qh256_t *q,
    char out[257]
)
{
    static const char bits[4][3] = {
        "00",
        "01",
        "10",
        "11"
    };

    size_t i;

    assert(q != NULL);
    assert(out != NULL);

    for (i = 0; i < QH256_CELL_COUNT; ++i) {

        qh256_state_t state;

        bool ok =
            qh256_get(
                q,
                i,
                &state
            );

        assert(ok);

        out[(i * 2) + 0] =
            bits[(unsigned)state][0];

        out[(i * 2) + 1] =
            bits[(unsigned)state][1];
    }

    out[256] = '\0';
}


/* ============================================================
 * FNV-1a 64-bit
 *
 * Not cryptographic.
 * Only a deterministic structural checksum.
 * ============================================================ */

uint64_t
qh256_fnv1a64(const qh256_t *q)
{
    uint64_t hash =
        UINT64_C(14695981039346656037);

    size_t i;

    assert(q != NULL);

    for (i = 0; i < QH256_BYTES; ++i) {

        hash ^=
            (uint64_t)q->bytes[i];

        hash *=
            UINT64_C(1099511628211);
    }

    return hash;
}

#include "qh256.h"

#include <assert.h>
#include <stdio.h>
#include <string.h>


/* ============================================================
 * Test: CLEAR
 * ============================================================ */

static void
test_clear(void)
{
    qh256_t q;
    size_t i;

    qh256_clear(&q);

    for (i = 0; i < QH256_BYTES; ++i) {
        assert(q.bytes[i] == 0x00u);
    }
}


/* ============================================================
 * Test: all 128 cells
 * ============================================================ */

static void
test_states(void)
{
    qh256_t q;
    qh256_state_t state;
    size_t i;

    qh256_clear(&q);

    for (i = 0; i < QH256_CELL_COUNT; ++i) {

        qh256_state_t expected =
            (qh256_state_t)(i & 3u);

        assert(
            qh256_set(
                &q,
                i,
                expected
            )
        );

        assert(
            qh256_get(
                &q,
                i,
                &state
            )
        );

        assert(
            state == expected
        );
    }
}


/* ============================================================
 * Test: FILL + state counting
 * ============================================================ */

static void
test_fill_and_count(void)
{
    qh256_t q;

    size_t unknown;
    size_t false_count;
    size_t true_count;
    size_t guard;


    qh256_fill(
        &q,
        QH256_UNKNOWN
    );

    qh256_count_states(
        &q,
        &unknown,
        &false_count,
        &true_count,
        &guard
    );

    assert(
        unknown == 128
        && false_count == 0
        && true_count == 0
        && guard == 0
    );


    qh256_fill(
        &q,
        QH256_FALSE
    );

    qh256_count_states(
        &q,
        &unknown,
        &false_count,
        &true_count,
        &guard
    );

    assert(
        unknown == 0
        && false_count == 128
        && true_count == 0
        && guard == 0
    );


    qh256_fill(
        &q,
        QH256_TRUE
    );

    qh256_count_states(
        &q,
        &unknown,
        &false_count,
        &true_count,
        &guard
    );

    assert(
        unknown == 0
        && false_count == 0
        && true_count == 128
        && guard == 0
    );


    qh256_fill(
        &q,
        QH256_GUARD
    );

    qh256_count_states(
        &q,
        &unknown,
        &false_count,
        &true_count,
        &guard
    );

    assert(
        unknown == 0
        && false_count == 0
        && true_count == 0
        && guard == 128
    );
}


/* ============================================================
 * Test: Byte representation
 * ============================================================ */

static void
test_serialization(void)
{
    qh256_t a;
    qh256_t b;

    uint8_t bytes[QH256_BYTES];


    qh256_clear(&a);


    /*
     * Byte 0:
     *
     * cell 0 = TRUE    = 10
     * cell 1 = FALSE   = 01
     * cell 2 = GUARD   = 11
     * cell 3 = UNKNOWN = 00
     *
     * Numeric byte value:
     *
     * 00 | 11<<4 | 01<<2 | 10
     *
     * = 0x36
     */

    assert(
        qh256_set(
            &a,
            0,
            QH256_TRUE
        )
    );

    assert(
        qh256_set(
            &a,
            1,
            QH256_FALSE
        )
    );

    assert(
        qh256_set(
            &a,
            2,
            QH256_GUARD
        )
    );

    assert(
        qh256_set(
            &a,
            3,
            QH256_UNKNOWN
        )
    );


    /*
     * Last cell:
     *
     * cell 127 = TRUE = 10
     *
     * Bits 6..7 of byte 31.
     */

    assert(
        qh256_set(
            &a,
            127,
            QH256_TRUE
        )
    );


    qh256_to_bytes(
        &a,
        bytes
    );


    assert(
        bytes[0] == 0x36u
    );


    assert(
        (bytes[31] & 0xC0u)
        == 0x80u
    );


    assert(
        qh256_from_bytes(
            &b,
            bytes
        )
    );


    assert(
        qh256_equal(
            &a,
            &b
        )
    );
}


/* ============================================================
 * Test: Bitstring
 * ============================================================ */

static void
test_bitstring(void)
{
    qh256_t q;
    char s[257];


    qh256_clear(&q);


    assert(
        qh256_set(
            &q,
            0,
            QH256_UNKNOWN
        )
    );

    assert(
        qh256_set(
            &q,
            1,
            QH256_FALSE
        )
    );

    assert(
        qh256_set(
            &q,
            2,
            QH256_TRUE
        )
    );

    assert(
        qh256_set(
            &q,
            3,
            QH256_GUARD
        )
    );


    qh256_to_bitstring(
        &q,
        s
    );


    assert(
        strlen(s) == 256u
    );


    assert(
        strncmp(
            s,
            "00011011",
            8
        ) == 0
    );
}


/* ============================================================
 * Main
 * ============================================================ */

int
main(void)
{
    test_clear();
    test_states();
    test_fill_and_count();
    test_serialization();
    test_bitstring();

    printf(
        "QH256 reference tests: PASS\n"
    );

    return 0;
}

gcc \
    -std=c11 \
    -O2 \
    -Wall \
    -Wextra \
    -Wpedantic \
    -Wconversion \
    -Wshadow \
    -Werror \
    qh256.c \
    test_qh256.c \
    -o test_qh256

./test_qh256

QH256 reference tests: PASS

cell 0 = TRUE
cell 1 = FALSE
cell 2 = GUARD
cell 3 = UNKNOWN

cell 0 = 10
cell 1 = 01
cell 2 = 11
cell 3 = 00

00 11 01 10

0x36

32 bytes

128 × 2-bit cells

256 binary digits

QH256
  │
  ├── 128 cells × 2 bit
  │
  ├── 32-byte binary representation
  │
  └── 256-character bit representation

uint64_t qh256_fnv1a64(
    const qh256_t *q
);

FNV-1a
=
deterministic structural checksum

not

cryptographic proof

LLM code
Embedding code
GPU code
Vulkan code
CUDA code
Quantization code
Network code
Database code

1024 dimensions × 1 bit
=
1024 bits
=
4 × 256 bits

1024-bit vector code
≠ QH256 semantic object

K501 Vector Block 256

QH256
=
canonical K501 state structure

Vector Block 256
=
technical 256-bit compute representation

QH256 semantics
    remain fixed
         │
         │
         ▼
256-bit technical representations
    may be used independently

QH256 state meanings
    are not quantization states

embedding quantization
    does not redefine QH256

Canonical Data
      │
      ├── QH256 structural state
      │
      └── Derived data
             │
             ├── Embeddings
             │
             ├── Quantized vectors
             │
             └── Vector Block 256

Canonical
    ↓
Derived
    ↓
Compute Index

Compute Index
    ↓
Canonical Truth

DETERMINISTIC
APPEND-ONLY
NO-DRIFT
NO-INTERPRETATION
PROOF BEFORE STATE
CANONICAL DATA FIRST
DERIVED DATA SEPARATION
RECONSTRUCTABILITY

fixed dimensions
explicit states
explicit packing
explicit serialization
explicit tests
explicit separation

{
  "namespace": "K501-Aionarc",
  "object": "QH256",
  "status": "CANONICAL",
  "cells": 128,
  "bits_per_cell": 2,
  "total_bits": 256,
  "total_bytes": 32,
  "state_encoding": {
    "UNKNOWN": "00",
    "FALSE": "01",
    "TRUE": "10",
    "GUARD": "11"
  },
  "cells_per_byte": 4,
  "representation": "uint8_t[32]",
  "semantic_separation": true,
  "embedding_format": false,
  "quantization_format": false,
  "deterministic_serialization": true,
  "language": "C11"
}

QH256 reference tests: PASS

QH256 specification:
CANONICAL / UNCHANGED

C reference implementation:
REFERENCE IMPLEMENTATION

State encoding:
CANONICAL

Binary layout:
EXPLICIT

Serialization:
DEFINED

Test suite:
IMPLEMENTED

Embedding integration:
SEPARATE / DERIVED

Quantized vector integration:
EXPERIMENTAL

Vulkan compute:
NOT PART OF THIS IMPLEMENTATION

GPU performance:
NOT CLAIMED

read
↓
compile
↓
run
↓
inspect
↓
modify
↓
compare

128 cells
×
2 bits
=
256 bits
=
32 bytes

00 UNKNOWN
01 FALSE
10 TRUE
11 GUARD

cell_index = 0
byte_index = 0
shift = 0

cell_index = 1
byte_index = 0
shift = 2

cell_index = 2
byte_index = 0
shift = 4

cell_index = 3
byte_index = 0
shift = 6

cell_index / 4

(cell_index % 4) × 2

QH256
=
QH256

256 bits

a vector representation

a derived vector representation

a compute representation

Namespace:      K501-Aionarc

Unix Epoch:     1786954613

Time (UTC):
2026-08-17 08:16:53 UTC

Time (Europe/Berlin):
2026-08-17 10:16:53 CEST

Status:
REFERENCE IMPLEMENTATION

Mode:
DETERMINISTIC
APPEND-ONLY
NO-DRIFT
NO-INTERPRETATION

QH256 = 128 × 2-bit cells = 256 bits.

UNKNOWN = 00
FALSE   = 01
TRUE    = 10
GUARD   = 11

QH256 remains structurally defined.

No semantic reinterpretation.
No silent extension.
No drift.

Structure precedes interpretation.
Proof before state.
Reconstruction before extension.