// ace_pool_connector.h - ACE-Pool Connection Box
// Box Theory: Single Responsibility - Validate and route ACE ↔ Pool connections
//
// Purpose:
//   - Make ACE-Pool connection VISIBLE and VALIDATED
//   - Centralize error handling and logging
//   - Health check API for diagnostics
//
// Responsibilities:
//   ✅ Validate Pool is initialized before ACE uses it
//   ✅ Log connection status (success/failure/reason)
//   ✅ Provide health check API
//   ❌ NOT responsible for: allocation logic, size rounding, or memory management
//
// Box Boundaries:
//   INPUT:  ACE requests allocation from Pool (size, site_id)
//   OUTPUT: Pool allocation result (ptr or NULL) + reason code
//   ERROR:  Clear error messages (not silent failures!)

#ifndef ACE_POOL_CONNECTOR_H
#define ACE_POOL_CONNECTOR_H

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

// ============================================================================
// Box API: ACE-Pool Connection
// ============================================================================

// Connection status codes
typedef enum {
    ACE_POOL_OK = 0,           // Connection healthy
    ACE_POOL_NOT_INIT,         // Pool not initialized
    ACE_POOL_NO_PAGES,         // Pool has no pre-allocated pages
    ACE_POOL_WRAPPER_BLOCKED,  // Wrapper protection blocking
    ACE_POOL_SIZE_MISMATCH,    // Size not in Pool range
    ACE_POOL_ALLOC_FAILED,     // Pool allocation returned NULL
} AcePoolStatus;

// Health check result
typedef struct {
    int pool_initialized;      // 1 if Pool is initialized
    int ace_enabled;           // 1 if ACE is enabled
    int wrap_l2_enabled;       // 1 if WRAP_L2 is enabled
    int bridge_class_5_size;   // Size of Bridge class 5 (40KB expected)
    int bridge_class_6_size;   // Size of Bridge class 6 (52KB expected)
    int preallocated_pages;    // Number of pre-allocated pages (should be > 0)
    AcePoolStatus status;      // Overall status
    const char* message;       // Human-readable status message
} AcePoolHealth;

// ============================================================================
// Box Functions
// ============================================================================

// Get health status (for debugging and monitoring)
AcePoolHealth ace_pool_get_health(void);

// Validate connection is ready (called by ACE before using Pool)
// Returns: 1 if ready, 0 if not (sets reason code)
int ace_pool_validate_connection(AcePoolStatus* out_status);

// Connect ACE to Pool (wrapper around hak_pool_try_alloc with validation)
// Returns: Allocated pointer or NULL (logs reason if NULL)
void* ace_pool_try_alloc(size_t size, uintptr_t site_id, AcePoolStatus* out_status);

// Print health status (for debugging)
void ace_pool_print_health(void);

#endif // ACE_POOL_CONNECTOR_H