/**
 * @file ptr_conversion_box.h
 * @brief Box 3: Unified Pointer Conversion Layer
 *
 * MISSION: Fix BASE/USER pointer confusion across codebase
 *
 * DESIGN:
 * - BASE pointer: Points to start of block in storage (0-byte aligned)
 * - USER pointer: Points to usable memory (+1 byte for classes 0-6, +0 for class 7)
 * - Class 7 (2KB) is headerless (no +1 offset)
 * - Classes 0-6 have 1-byte header (need +1 offset)
 *
 * BOX BOUNDARIES:
 * - Box 1 (Front Gate) → Box 3 → Box 4 (User)  [BASE to USER]
 * - Box 4 (User) → Box 3 → Box 1 (Front Gate)  [USER to BASE]
 */

#ifndef HAKMEM_PTR_CONVERSION_BOX_H
#define HAKMEM_PTR_CONVERSION_BOX_H

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

#ifdef HAKMEM_PTR_CONVERSION_DEBUG
#include <stdio.h>
#define PTR_CONV_LOG(...) fprintf(stderr, "[PTR_CONV] " __VA_ARGS__)
#else
#define PTR_CONV_LOG(...) ((void)0)
#endif

/**
 * Convert BASE pointer (storage) to USER pointer (returned to caller)
 * Phase E1-CORRECT: ALL classes (0-7) have 1-byte headers
 *
 * @param base_ptr Pointer to block in storage (no offset)
 * @param class_idx Size class (0-7: +1 offset for all)
 * @return USER pointer (usable memory address)
 */
static inline void* ptr_base_to_user(void* base_ptr, uint8_t class_idx) {
    if (base_ptr == NULL) {
        return NULL;
    }

    /* Phase E1-CORRECT: All classes 0-7 have 1-byte header - skip it */
    void* user_ptr = (void*)((uint8_t*)base_ptr + 1);
    PTR_CONV_LOG("BASE→USER cls=%u base=%p → user=%p (+1 offset)\n",
                 class_idx, base_ptr, user_ptr);
    return user_ptr;
}

/**
 * Convert USER pointer (from caller) to BASE pointer (storage)
 * Phase E1-CORRECT: ALL classes (0-7) have 1-byte headers
 *
 * @param user_ptr Pointer from user (may have +1 offset)
 * @param class_idx Size class (0-7: -1 offset for all)
 * @return BASE pointer (block start in storage)
 */
static inline void* ptr_user_to_base(void* user_ptr, uint8_t class_idx) {
    if (user_ptr == NULL) {
        return NULL;
    }

    /* Phase E1-CORRECT: All classes 0-7 have 1-byte header - rewind it */
    void* base_ptr = (void*)((uint8_t*)user_ptr - 1);
    PTR_CONV_LOG("USER→BASE cls=%u user=%p → base=%p (-1 offset)\n",
                 class_idx, user_ptr, base_ptr);
    return base_ptr;
}

/**
 * Convenience macros for cleaner call sites
 */
#define PTR_BASE_TO_USER(base, cls) ptr_base_to_user((base), (cls))
#define PTR_USER_TO_BASE(user, cls) ptr_user_to_base((user), (cls))

#endif /* HAKMEM_PTR_CONVERSION_BOX_H */