hakmem/core/box/integrity_box.h

// integrity_box.h - Box I: Integrity Verification System
// Purpose: Beautiful modular integrity checking with Priority ALPHA metadata validation
// Author: Claude + Task (2025-11-12)
//
// Box I provides layered integrity checks with compile-time control:
// - Level 0: No checks (release builds)
// - Level 1: TLS bounds checking
// - Level 2: Level 1 + freelist pointer validation
// - Level 3: Level 2 + TLS canary validation
// - Level 4: Level 3 + Priority ALPHA slab metadata validation (THE KEY!)
//
// This system is designed to catch the P0 SEGV bug at iteration 28,440 by
// detecting metadata corruption BEFORE it causes a crash.

#ifndef INTEGRITY_BOX_H
#define INTEGRITY_BOX_H

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

// ============================================================================
// Integrity Level Configuration
// ============================================================================

#ifndef HAKMEM_INTEGRITY_LEVEL
    #ifdef NDEBUG
        #define HAKMEM_INTEGRITY_LEVEL 0  // No checks in release
    #else
        #define HAKMEM_INTEGRITY_LEVEL 4  // Full checks in debug (Priority ALPHA enabled)
    #endif
#endif

// ============================================================================
// Core Types
// ============================================================================

// Result of an integrity check
typedef struct {
    bool passed;                    // True if check passed
    const char* check_name;         // Name of the check (e.g., "METADATA_CARVED_OVERFLOW")
    const char* file;               // File where check was performed
    int line;                       // Line number
    const char* message;            // Human-readable description
    uint32_t error_code;            // Unique error code (0x0000 = OK, 0xA001+ = metadata errors)
} IntegrityResult;

// Priority ALPHA: Slab metadata state snapshot
typedef struct {
    // Core metadata fields (from TinySlabMeta)
    uint16_t carved;                // Blocks carved from linear region (monotonic)
    uint16_t used;                  // Blocks currently in use
    uint16_t capacity;              // Total blocks in slab
    void* freelist;                 // Freelist head (NULL in linear mode)

    // Context
    void* slab_base;                // Base address of the slab
    uint8_t class_idx;              // Size class index (0-7)

    // Derived state (computed for validation)
    uint16_t free_count;            // Should equal (carved - used)
    bool is_virgin;                 // carved == 0 (never allocated from)
    bool is_full;                   // carved == capacity && used == capacity
    bool is_empty;                  // used == 0 (all freed)
} SlabMetadataState;

// TLS state snapshot (for comprehensive checks)
typedef struct {
    void* sll_head[8];              // TLS SLL heads for each class
    uint32_t sll_count[8];          // TLS SLL counts for each class
    uint64_t canary_before_head;    // Canary before sll_head array
    uint64_t canary_after_head;     // Canary after sll_head array
    uint64_t canary_before_count;   // Canary before sll_count array
    uint64_t canary_after_count;    // Canary after sll_count array
} TLSStateSnapshot;

// Global integrity statistics
typedef struct {
    uint64_t checks_performed;      // Total checks run
    uint64_t checks_passed;         // Total checks that passed
    uint64_t checks_failed;         // Total checks that failed
    uint64_t tls_bounds_checks;     // TLS bounds checks
    uint64_t freelist_checks;       // Freelist pointer checks
    uint64_t metadata_checks;       // Slab metadata checks (Priority ALPHA)
    uint64_t canary_checks;         // TLS canary checks
    uint64_t full_system_checks;    // Full system integrity scans
} IntegrityStatistics;

// ============================================================================
// Core API
// ============================================================================

// Initialize Box I
void integrity_box_init(void);

// Priority 1: TLS Bounds Validation
// Checks that class_idx is within valid range [0, TINY_NUM_CLASSES)
IntegrityResult integrity_validate_tls_bounds(
    uint8_t class_idx,
    const char* context
);

// Priority 2: Freelist Pointer Validation
// Checks that freelist pointer is within slab bounds and properly aligned
IntegrityResult integrity_validate_freelist_ptr(
    void* ptr,
    void* slab_base,
    void* slab_end,
    uint8_t class_idx,
    const char* context
);

// Priority 3: TLS Canary Validation
// Checks that TLS canaries are intact (detects buffer overflows)
IntegrityResult integrity_validate_tls_canaries(
    const char* context
);

// Priority ALPHA: Slab Metadata Validation (THE KEY!)
// Validates slab metadata invariants:
// - carved <= capacity
// - used <= carved
// - used <= capacity
// - free_count == (carved - used)
// - capacity is reasonable (<= 512)
IntegrityResult integrity_validate_slab_metadata(
    const SlabMetadataState* state,
    const char* context
);

// Capture slab metadata state for validation
SlabMetadataState integrity_capture_slab_metadata(
    const void* meta_ptr,
    void* slab_base,
    uint8_t class_idx
);

// Periodic full system integrity check
// Scans all TLS structures and active slabs
void integrity_periodic_full_check(
    const char* context
);

// ============================================================================
// Statistics API
// ============================================================================

// Get current integrity statistics
IntegrityStatistics integrity_get_statistics(void);

// Print integrity statistics to stderr
void integrity_print_statistics(void);

// ============================================================================
// Convenience Macros
// ============================================================================

#if HAKMEM_INTEGRITY_LEVEL >= 1
    #define INTEGRITY_CHECK_TLS_BOUNDS(cls, ctx) do { \
        IntegrityResult _ir = integrity_validate_tls_bounds((cls), (ctx)); \
        if (!_ir.passed) { \
            fprintf(stderr, "[INTEGRITY FAILURE] %s at %s:%d - %s (error 0x%04X)\n", \
                    _ir.check_name, _ir.file, _ir.line, _ir.message, _ir.error_code); \
            abort(); \
        } \
    } while(0)
#else
    #define INTEGRITY_CHECK_TLS_BOUNDS(cls, ctx) ((void)0)
#endif

#if HAKMEM_INTEGRITY_LEVEL >= 2
    #define INTEGRITY_CHECK_FREELIST_PTR(ptr, base, end, cls, ctx) do { \
        IntegrityResult _ir = integrity_validate_freelist_ptr((ptr), (base), (end), (cls), (ctx)); \
        if (!_ir.passed) { \
            fprintf(stderr, "[INTEGRITY FAILURE] %s at %s:%d - %s (error 0x%04X)\n", \
                    _ir.check_name, _ir.file, _ir.line, _ir.message, _ir.error_code); \
            abort(); \
        } \
    } while(0)
#else
    #define INTEGRITY_CHECK_FREELIST_PTR(ptr, base, end, cls, ctx) ((void)0)
#endif

#if HAKMEM_INTEGRITY_LEVEL >= 3
    #define INTEGRITY_CHECK_CANARIES(ctx) do { \
        IntegrityResult _ir = integrity_validate_tls_canaries(ctx); \
        if (!_ir.passed) { \
            fprintf(stderr, "[INTEGRITY FAILURE] %s at %s:%d - %s (error 0x%04X)\n", \
                    _ir.check_name, _ir.file, _ir.line, _ir.message, _ir.error_code); \
            abort(); \
        } \
    } while(0)
#else
    #define INTEGRITY_CHECK_CANARIES(ctx) ((void)0)
#endif

#if HAKMEM_INTEGRITY_LEVEL >= 4
    #define INTEGRITY_CHECK_SLAB_METADATA(state, ctx) do { \
        IntegrityResult _ir = integrity_validate_slab_metadata(&(state), (ctx)); \
        if (!_ir.passed) { \
            fprintf(stderr, "[INTEGRITY FAILURE] %s at %s:%d - %s (error 0x%04X)\n", \
                    _ir.check_name, _ir.file, _ir.line, _ir.message, _ir.error_code); \
            fprintf(stderr, "  Metadata: carved=%u used=%u capacity=%u free_count=%u class=%u\n", \
                    (state).carved, (state).used, (state).capacity, (state).free_count, (state).class_idx); \
            abort(); \
        } \
    } while(0)
#else
    #define INTEGRITY_CHECK_SLAB_METADATA(state, ctx) ((void)0)
#endif

// ============================================================================
// Error Codes
// ============================================================================

// 0x0000: Success
// 0xA001-0xA0FF: Slab metadata errors (Priority ALPHA)
// 0xB001-0xB0FF: TLS bounds errors (Priority 1)
// 0xC001-0xC0FF: Freelist pointer errors (Priority 2)
// 0xD001-0xD0FF: TLS canary errors (Priority 3)

#define INTEGRITY_ERROR_OK                          0x0000

// Priority ALPHA: Metadata errors
#define INTEGRITY_ERROR_METADATA_CARVED_OVERFLOW    0xA001
#define INTEGRITY_ERROR_METADATA_USED_GT_CARVED     0xA002
#define INTEGRITY_ERROR_METADATA_USED_OVERFLOW      0xA003
#define INTEGRITY_ERROR_METADATA_FREE_COUNT_MISMATCH 0xA004
#define INTEGRITY_ERROR_METADATA_CAPACITY_UNREASONABLE 0xA005

// Priority 1: TLS bounds errors
#define INTEGRITY_ERROR_TLS_BOUNDS_OVERFLOW         0xB001

// Priority 2: Freelist pointer errors
#define INTEGRITY_ERROR_FREELIST_PTR_OUT_OF_BOUNDS  0xC001
#define INTEGRITY_ERROR_FREELIST_PTR_MISALIGNED     0xC002

// Priority 3: TLS canary errors
#define INTEGRITY_ERROR_CANARY_CORRUPTED_BEFORE_HEAD 0xD001
#define INTEGRITY_ERROR_CANARY_CORRUPTED_AFTER_HEAD  0xD002
#define INTEGRITY_ERROR_CANARY_CORRUPTED_BEFORE_COUNT 0xD003
#define INTEGRITY_ERROR_CANARY_CORRUPTED_AFTER_COUNT  0xD004

#endif // INTEGRITY_BOX_H