engine.c

#include "../include/gs_engine.h"
#include "../include/gs_memory.h"
#include "../include/gs_vertex.h"
#include "../include/gs_edge.h"
#include "../include/gs_planner_internal.h"
#include "../include/gs_cache.h"
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <time.h>
#include <assert.h>

// Provider registration entry
typedef struct {
    char* name;
    gs_generate_edges_fn outgoing_generator;
    gs_generate_incoming_edges_fn incoming_generator;
    void* user_data;
    bool is_enabled;
    bool supports_incoming;  // Whether this provider has incoming edge support
} Provider;

// Engine structure
struct GraphserverEngine {
    Provider* providers;
    size_t provider_count;
    size_t provider_capacity;
    
    GraphserverEngineConfig config;
    
    // Edge cache for vertex expansion acceleration
    EdgeCache* edge_cache;
    
    // Statistics
    GraphserverPlanStats last_plan_stats;
    
    // Future: thread pool for concurrent expansion
    // ThreadPool* thread_pool;
};

// Path structure (basic implementation for now)
struct GraphserverPath {
    GraphserverEdge** edges;
    size_t num_edges;
    double* total_cost;
    size_t cost_vector_size;
};

// Path list structure
struct GraphserverPathList {
    GraphserverPath** paths;
    size_t num_paths;
    size_t capacity;
};

// Helper function to duplicate string
static char* duplicate_string(const char* str) {
    if (!str) return NULL;
    
    size_t len = strlen(str);
    char* copy = malloc(len + 1);
    if (!copy) return NULL;
    
    memcpy(copy, str, len + 1);
    return copy;
}

// Helper function to find provider by name
static Provider* find_provider(GraphserverEngine* engine, const char* name) {
    if (!engine || !name) return NULL;
    
    for (size_t i = 0; i < engine->provider_count; i++) {
        if (strcmp(engine->providers[i].name, name) == 0) {
            return &engine->providers[i];
        }
    }
    
    return NULL;
}

// Helper function to ensure provider capacity
static GraphserverResult ensure_provider_capacity(GraphserverEngine* engine, size_t min_capacity) {
    if (engine->provider_capacity >= min_capacity) return GS_SUCCESS;
    
    size_t new_capacity = engine->provider_capacity == 0 ? 4 : engine->provider_capacity * 2;
    while (new_capacity < min_capacity) {
        new_capacity *= 2;
    }
    
    Provider* new_providers = realloc(engine->providers, sizeof(Provider) * new_capacity);
    if (!new_providers) return GS_ERROR_OUT_OF_MEMORY;
    
    engine->providers = new_providers;
    engine->provider_capacity = new_capacity;
    
    return GS_SUCCESS;
}

// Get default configuration
GraphserverEngineConfig gs_engine_get_default_config(void) {
    GraphserverEngineConfig config = {0};
    config.default_arena_size = GS_DEFAULT_ARENA_SIZE;
    config.max_memory_limit = 0; // No limit
    config.default_timeout_seconds = 30.0; // 30 seconds
    config.enable_concurrent_expansion = false; // Not implemented yet
    config.max_worker_threads = 4;
    config.enable_edge_caching = false; // Disabled by default
    
    return config;
}

// Engine lifecycle
GraphserverEngine* gs_engine_create(void) {
    GraphserverEngineConfig config = gs_engine_get_default_config();
    return gs_engine_create_with_config(&config);
}

GraphserverEngine* gs_engine_create_with_config(const GraphserverEngineConfig* config) {
    if (!config) return NULL;
    
    GraphserverEngine* engine = malloc(sizeof(GraphserverEngine));
    if (!engine) return NULL;
    
    engine->providers = NULL;
    engine->provider_count = 0;
    engine->provider_capacity = 0;
    engine->config = *config;
    
    // Initialize edge cache if enabled
    if (config->enable_edge_caching) {
        engine->edge_cache = edge_cache_create();
        if (!engine->edge_cache) {
            free(engine);
            return NULL;
        }
    } else {
        engine->edge_cache = NULL;
    }
    
    // Initialize stats
    memset(&engine->last_plan_stats, 0, sizeof(GraphserverPlanStats));
    
    return engine;
}

void gs_engine_destroy(GraphserverEngine* engine) {
    if (!engine) return;
    
    // Free provider names
    for (size_t i = 0; i < engine->provider_count; i++) {
        free(engine->providers[i].name);
    }
    
    // Destroy edge cache
    if (engine->edge_cache) {
        edge_cache_destroy(engine->edge_cache);
    }
    
    free(engine->providers);
    free(engine);
}

// Internal helper function to clear the cache and reset statistics (used internally)
static void gs_engine_clear_cache_internal(GraphserverEngine* engine) {
    if (!engine) return;
    
    // Clear the cache if caching is enabled and cache exists
    if (engine->config.enable_edge_caching && engine->edge_cache) {
        edge_cache_clear(engine->edge_cache);
        
        // Reset cache statistics
        engine->last_plan_stats.cache_hits = 0;
        engine->last_plan_stats.cache_misses = 0;
        engine->last_plan_stats.cache_puts = 0;
    }
}

// Public cache invalidation functions

GraphserverResult gs_engine_invalidate_vertex_cache(
    GraphserverEngine* engine,
    const GraphserverVertex* vertex) {
    
    if (!engine || !vertex) {
        return GS_ERROR_NULL_POINTER;
    }
    
    // Only proceed if caching is enabled and cache exists
    if (!engine->config.enable_edge_caching || !engine->edge_cache) {
        return GS_SUCCESS; // Nothing to invalidate
    }
    
    return edge_cache_invalidate(engine->edge_cache, vertex);
}

GraphserverResult gs_engine_invalidate_vertices_cache(
    GraphserverEngine* engine,
    const GraphserverVertex** vertices,
    size_t count) {
    
    if (!engine || !vertices) {
        return GS_ERROR_NULL_POINTER;
    }
    
    // Only proceed if caching is enabled and cache exists
    if (!engine->config.enable_edge_caching || !engine->edge_cache) {
        return GS_SUCCESS; // Nothing to invalidate
    }
    
    return edge_cache_invalidate_batch(engine->edge_cache, vertices, count);
}

GraphserverResult gs_engine_clear_cache(GraphserverEngine* engine) {
    if (!engine) {
        return GS_ERROR_NULL_POINTER;
    }
    
    // Only proceed if caching is enabled and cache exists
    if (!engine->config.enable_edge_caching || !engine->edge_cache) {
        return GS_SUCCESS; // Nothing to clear
    }
    
    edge_cache_invalidate_all(engine->edge_cache);
    
    // Reset cache statistics
    engine->last_plan_stats.cache_hits = 0;
    engine->last_plan_stats.cache_misses = 0;
    engine->last_plan_stats.cache_puts = 0;
    
    return GS_SUCCESS;
}

// Provider management
GraphserverResult gs_engine_register_provider(
    GraphserverEngine* engine,
    const char* provider_name,
    gs_generate_edges_fn generator_func,
    void* user_data) {
    
    if (!engine || !provider_name || !generator_func) {
        return GS_ERROR_NULL_POINTER;
    }
    
    // Check if provider already exists
    if (find_provider(engine, provider_name) != NULL) {
        return GS_ERROR_INVALID_ARGUMENT; // Provider already exists
    }
    
    // Ensure capacity
    GraphserverResult result = ensure_provider_capacity(engine, engine->provider_count + 1);
    if (result != GS_SUCCESS) return result;
    
    // Add new provider
    Provider* provider = &engine->providers[engine->provider_count];
    provider->name = duplicate_string(provider_name);
    if (!provider->name) return GS_ERROR_OUT_OF_MEMORY;
    
    provider->outgoing_generator = generator_func;
    provider->incoming_generator = NULL;  // Legacy providers only support outgoing
    provider->user_data = user_data;
    provider->is_enabled = true;
    provider->supports_incoming = false;
    
    engine->provider_count++;
    
    // Clear cache since adding a provider changes graph topology
    gs_engine_clear_cache_internal(engine);
    
    return GS_SUCCESS;
}

GraphserverResult gs_engine_register_bidirectional_provider(
    GraphserverEngine* engine,
    const char* provider_name,
    gs_generate_edges_fn outgoing_generator,
    gs_generate_incoming_edges_fn incoming_generator,
    void* user_data) {
    
    if (!engine || !provider_name) {
        return GS_ERROR_NULL_POINTER;
    }
    
    // At least one generator must be provided
    if (!outgoing_generator && !incoming_generator) {
        return GS_ERROR_INVALID_ARGUMENT;
    }
    
    // Check if provider already exists
    if (find_provider(engine, provider_name) != NULL) {
        return GS_ERROR_INVALID_ARGUMENT; // Provider already exists
    }
    
    // Ensure capacity
    GraphserverResult result = ensure_provider_capacity(engine, engine->provider_count + 1);
    if (result != GS_SUCCESS) return result;
    
    // Add new provider
    Provider* provider = &engine->providers[engine->provider_count];
    provider->name = duplicate_string(provider_name);
    if (!provider->name) return GS_ERROR_OUT_OF_MEMORY;
    
    provider->outgoing_generator = outgoing_generator;
    provider->incoming_generator = incoming_generator;
    provider->user_data = user_data;
    provider->is_enabled = true;
    provider->supports_incoming = (incoming_generator != NULL);
    
    engine->provider_count++;
    
    // Clear cache since adding a provider changes graph topology
    if (engine->edge_cache) {
        edge_cache_clear(engine->edge_cache);
    }
    
    return GS_SUCCESS;
}

GraphserverResult gs_engine_unregister_provider(
    GraphserverEngine* engine,
    const char* provider_name) {
    
    if (!engine || !provider_name) return GS_ERROR_NULL_POINTER;
    
    // Find provider
    for (size_t i = 0; i < engine->provider_count; i++) {
        if (strcmp(engine->providers[i].name, provider_name) == 0) {
            // Free the name
            free(engine->providers[i].name);
            
            // Shift remaining providers down
            for (size_t j = i; j < engine->provider_count - 1; j++) {
                engine->providers[j] = engine->providers[j + 1];
            }
            
            engine->provider_count--;
            
            // Clear cache since removing a provider changes graph topology
            gs_engine_clear_cache_internal(engine);
            
            return GS_SUCCESS;
        }
    }
    
    return GS_ERROR_KEY_NOT_FOUND;
}

GraphserverResult gs_engine_set_provider_enabled(
    GraphserverEngine* engine,
    const char* provider_name,
    bool enabled) {
    
    if (!engine || !provider_name) return GS_ERROR_NULL_POINTER;
    
    Provider* provider = find_provider(engine, provider_name);
    if (!provider) return GS_ERROR_KEY_NOT_FOUND;
    
    provider->is_enabled = enabled;
    
    // Clear cache since enabling/disabling a provider changes graph topology
    gs_engine_clear_cache_internal(engine);
    
    return GS_SUCCESS;
}

GraphserverResult gs_engine_list_providers(
    const GraphserverEngine* engine,
    GraphserverProviderInfo** out_provider_info,
    size_t* out_count) {
    
    if (!engine || !out_provider_info || !out_count) {
        return GS_ERROR_NULL_POINTER;
    }
    
    if (engine->provider_count == 0) {
        *out_provider_info = NULL;
        *out_count = 0;
        return GS_SUCCESS;
    }
    
    GraphserverProviderInfo* info = malloc(sizeof(GraphserverProviderInfo) * engine->provider_count);
    if (!info) return GS_ERROR_OUT_OF_MEMORY;
    
    for (size_t i = 0; i < engine->provider_count; i++) {
        info[i].name = engine->providers[i].name;
        info[i].generator = engine->providers[i].outgoing_generator;
        info[i].user_data = engine->providers[i].user_data;
        info[i].is_enabled = engine->providers[i].is_enabled;
    }
    
    *out_provider_info = info;
    *out_count = engine->provider_count;
    
    return GS_SUCCESS;
}

size_t gs_engine_get_provider_count(const GraphserverEngine* engine) {
    return engine ? engine->provider_count : 0;
}

bool gs_engine_has_provider(const GraphserverEngine* engine, const char* provider_name) {
    return find_provider((GraphserverEngine*)engine, provider_name) != NULL;
}

// Attempt to load edges from the cache. Returns GS_SUCCESS on cache hit and
// GS_ERROR_KEY_NOT_FOUND on miss. Other errors are propagated so callers can
// decide how to proceed.
static GraphserverResult try_cache(
    GraphserverEngine* engine,
    const GraphserverVertex* vertex,
    GraphserverEdgeList* out_edges)
{
    if (!engine || !vertex || !out_edges) {
        return GS_ERROR_NULL_POINTER;
    }

    if (!engine->config.enable_edge_caching || !engine->edge_cache) {
        return GS_ERROR_KEY_NOT_FOUND;
    }

    GraphserverEdgeList* cached_edges = NULL;
    GraphserverResult cache_result = edge_cache_get(engine->edge_cache, vertex, &cached_edges);

    if (cache_result == GS_SUCCESS && cached_edges) {
        size_t cached_edge_count = gs_edge_list_get_count(cached_edges);
        
        for (size_t i = 0; i < cached_edge_count; i++) {
            GraphserverEdge* edge;
            if (gs_edge_list_get_edge(cached_edges, i, &edge) == GS_SUCCESS && edge) {
                GraphserverEdge* edge_clone = gs_edge_clone(edge);
                if (edge_clone) {
                    gs_edge_list_add_edge(out_edges, edge_clone);
                }
            }
        }

        engine->last_plan_stats.cache_hits++;
        engine->last_plan_stats.edges_generated += cached_edge_count;

        gs_edge_list_destroy(cached_edges);
        return GS_SUCCESS;
    }

    if (cache_result == GS_ERROR_KEY_NOT_FOUND) {
        engine->last_plan_stats.cache_misses++;
    }

    if (cached_edges) {
        gs_edge_list_destroy(cached_edges);
    }

    return cache_result;
}

// Invoke all enabled providers to generate edges for a vertex.
// Returns GS_SUCCESS unless a memory allocation failure occurs.
static GraphserverResult call_providers(
    GraphserverEngine* engine,
    const GraphserverVertex* vertex,
    GraphserverEdgeList* out_edges)
{
    if (!engine || !vertex || !out_edges) {
        return GS_ERROR_NULL_POINTER;
    }

    GraphserverResult overall_result = GS_SUCCESS;

    for (size_t i = 0; i < engine->provider_count; i++) {
        Provider* provider = &engine->providers[i];
        if (!provider->is_enabled) {
            continue;
        }

        GraphserverEdgeList* provider_edges = gs_edge_list_create();
        if (!provider_edges) {
            overall_result = GS_ERROR_OUT_OF_MEMORY;
            break;
        }

        // Use outgoing generator for normal expansion
        int provider_result = provider->outgoing_generator ? 
            provider->outgoing_generator(vertex, provider_edges, provider->user_data) : -1;

        if (provider_result == 0) {
            size_t provider_edge_count = gs_edge_list_get_count(provider_edges);
            
            for (size_t j = 0; j < provider_edge_count; j++) {
                GraphserverEdge* edge;
                if (gs_edge_list_get_edge(provider_edges, j, &edge) == GS_SUCCESS && edge) {
                    gs_edge_list_add_edge(out_edges, edge);
                }
            }

            engine->last_plan_stats.providers_called++;
            engine->last_plan_stats.edges_generated += provider_edge_count;
        }

        gs_edge_list_destroy(provider_edges);
    }

    return overall_result;
}

// Graph expansion
GraphserverResult gs_engine_expand_vertex(
    GraphserverEngine* engine,
    const GraphserverVertex* vertex,
    GraphserverEdgeList* out_edges) {
    
    if (!engine || !vertex || !out_edges) return GS_ERROR_NULL_POINTER;
    
    // Clear the output edge list
    gs_edge_list_clear(out_edges);
    
    // Try retrieving from cache first
    GraphserverResult cache_result = try_cache(engine, vertex, out_edges);
    if (cache_result == GS_SUCCESS) {
        return GS_SUCCESS;
    }

    // Cache miss or error - generate edges using providers
    GraphserverResult overall_result = call_providers(engine, vertex, out_edges);

    // Store results in cache if caching is enabled and providers succeeded
    if (engine->config.enable_edge_caching && engine->edge_cache && overall_result == GS_SUCCESS) {
        (void)edge_cache_put(engine->edge_cache, vertex, out_edges);
        engine->last_plan_stats.cache_puts++;
    }

    return overall_result;
}

// Invoke all enabled providers to generate incoming edges for a vertex.
// Returns GS_SUCCESS unless a memory allocation failure occurs.
static GraphserverResult call_providers_incoming(
    GraphserverEngine* engine,
    const GraphserverVertex* vertex,
    GraphserverEdgeList* in_edges)
{
    if (!engine || !vertex || !in_edges) {
        return GS_ERROR_NULL_POINTER;
    }
    
    GraphserverResult overall_result = GS_SUCCESS;
    
    for (size_t i = 0; i < engine->provider_count; i++) {
        Provider* provider = &engine->providers[i];
        
        if (!provider->is_enabled || !provider->incoming_generator) {
            continue;
        }
        
        GraphserverEdgeList* provider_edges = gs_edge_list_create();
        if (!provider_edges) {
            overall_result = GS_ERROR_OUT_OF_MEMORY;
            break;
        }
        
        int provider_result = provider->incoming_generator(vertex, provider_edges, provider->user_data);
        
        if (provider_result == 0) {
            size_t provider_edge_count = gs_edge_list_get_count(provider_edges);
            for (size_t j = 0; j < provider_edge_count; j++) {
                GraphserverEdge* edge;
                if (gs_edge_list_get_edge(provider_edges, j, &edge) == GS_SUCCESS && edge) {
                    gs_edge_list_add_edge(in_edges, edge);
                }
            }
            engine->last_plan_stats.edges_generated += provider_edge_count;
        }
        
        engine->last_plan_stats.providers_called++;
        gs_edge_list_destroy(provider_edges);
    }
    
    return overall_result;
}

GraphserverResult gs_engine_expand_vertex_incoming(
    GraphserverEngine* engine,
    const GraphserverVertex* vertex,
    GraphserverEdgeList* in_edges) {
    
    if (!engine || !vertex || !in_edges) return GS_ERROR_NULL_POINTER;
    
    // Clear the output edge list
    gs_edge_list_clear(in_edges);
    
    // For now, incoming edges are not cached (could be added later with separate cache)
    // Generate edges using providers directly
    GraphserverResult overall_result = call_providers_incoming(engine, vertex, in_edges);
    
    return overall_result;
}

// Configuration
GraphserverResult gs_engine_set_config(
    GraphserverEngine* engine,
    const GraphserverEngineConfig* config) {
    
    if (!engine || !config) return GS_ERROR_NULL_POINTER;
    
    // Check if caching configuration is changing
    bool caching_was_enabled = engine->config.enable_edge_caching;
    bool caching_will_be_enabled = config->enable_edge_caching;
    
    // Update configuration
    engine->config = *config;
    
    // Handle cache state changes
    if (caching_was_enabled && !caching_will_be_enabled) {
        // Caching is being disabled - destroy the cache
        if (engine->edge_cache) {
            edge_cache_destroy(engine->edge_cache);
            engine->edge_cache = NULL;
        }
        // Reset cache statistics
        engine->last_plan_stats.cache_hits = 0;
        engine->last_plan_stats.cache_misses = 0;
        engine->last_plan_stats.cache_puts = 0;
    } else if (!caching_was_enabled && caching_will_be_enabled) {
        // Caching is being enabled - create the cache
        engine->edge_cache = edge_cache_create();
        if (!engine->edge_cache) {
            return GS_ERROR_OUT_OF_MEMORY;
        }
    } else if (caching_was_enabled && caching_will_be_enabled) {
        // Caching remains enabled - clear the cache as configuration might affect edge generation
        gs_engine_clear_cache_internal(engine);
    }
    
    return GS_SUCCESS;
}

GraphserverResult gs_engine_get_config(
    const GraphserverEngine* engine,
    GraphserverEngineConfig* out_config) {
    
    if (!engine || !out_config) return GS_ERROR_NULL_POINTER;
    
    *out_config = engine->config;
    return GS_SUCCESS;
}

GraphserverResult gs_engine_get_stats(
    const GraphserverEngine* engine,
    GraphserverPlanStats* out_stats) {
    
    if (!engine || !out_stats) return GS_ERROR_NULL_POINTER;
    
    *out_stats = engine->last_plan_stats;
    return GS_SUCCESS;
}

// Basic path management (will be expanded when planners are implemented)
GraphserverPath* gs_path_create(size_t cost_vector_size) {
    GraphserverPath* path = malloc(sizeof(GraphserverPath));
    if (!path) return NULL;
    
    path->edges = NULL;
    path->num_edges = 0;
    path->cost_vector_size = cost_vector_size;
    
    if (cost_vector_size > 0) {
        path->total_cost = calloc(cost_vector_size, sizeof(double));
        if (!path->total_cost) {
            free(path);
            return NULL;
        }
    } else {
        path->total_cost = NULL;
    }
    
    return path;
}

void gs_path_destroy(GraphserverPath* path) {
    if (!path) return;
    
    // Destroy individual edges
    if (path->edges) {
        for (size_t i = 0; i < path->num_edges; i++) {
            if (path->edges[i]) {
                gs_edge_destroy(path->edges[i]);
            }
        }
        free(path->edges);
    }
    
    free(path->total_cost);
    free(path);
}

size_t gs_path_get_num_edges(const GraphserverPath* path) {
    return path ? path->num_edges : 0;
}

const GraphserverEdge* gs_path_get_edge(const GraphserverPath* path, size_t index) {
    if (!path || index >= path->num_edges) return NULL;
    return path->edges[index];
}

const double* gs_path_get_total_cost(const GraphserverPath* path) {
    return path ? path->total_cost : NULL;
}

size_t gs_path_get_cost_vector_size(const GraphserverPath* path) {
    return path ? path->cost_vector_size : 0;
}

char* gs_path_to_string(const GraphserverPath* path) {
    if (!path) return NULL;
    
    // Simple implementation for now
    char* buffer = malloc(256);
    if (!buffer) return NULL;
    
    snprintf(buffer, 256, "Path{edges: %zu, cost_size: %zu}", 
             path->num_edges, path->cost_vector_size);
    
    return buffer;
}

// Path list management
GraphserverPathList* gs_pathlist_create(void) {
    GraphserverPathList* list = malloc(sizeof(GraphserverPathList));
    if (!list) return NULL;
    
    list->paths = NULL;
    list->num_paths = 0;
    list->capacity = 0;
    
    return list;
}

void gs_pathlist_destroy(GraphserverPathList* path_list) {
    if (!path_list) return;
    
    for (size_t i = 0; i < path_list->num_paths; i++) {
        gs_path_destroy(path_list->paths[i]);
    }
    
    free(path_list->paths);
    free(path_list);
}

size_t gs_pathlist_get_count(const GraphserverPathList* path_list) {
    return path_list ? path_list->num_paths : 0;
}

GraphserverPath* gs_pathlist_get_path(const GraphserverPathList* path_list, size_t index) {
    if (!path_list || index >= path_list->num_paths) return NULL;
    return path_list->paths[index];
}

// Planning function implementations using Dijkstra algorithm

GraphserverPathList* gs_plan(
    GraphserverEngine* engine,
    const GraphserverPlanOptions* options,
    GraphserverPlanStats* out_stats) {
    
    if (!engine || !options) return NULL;
    
    // Preserve existing stats (e.g., from precaching) and only reset planning-specific counters
    // Keep: cache_hits, cache_misses, cache_puts, providers_called, edges_generated from precaching
    // Reset: vertices_expanded (will be set by planner)
    engine->last_plan_stats.vertices_expanded = 0;
    
    // Create arena for planning operations
    GraphserverArena* arena = gs_arena_create(engine->config.default_arena_size);
    if (!arena) return NULL;
    
    GraphserverPath* path = NULL;
    GraphserverPlanStats stats = {0};
    
    // Use Dijkstra planner (currently only single-objective supported)
    GraphserverResult result = gs_plan_dijkstra(
        engine,
        options->start_vertex,
        options->is_goal_fn,
        options->is_goal_user_data,
        options->timeout_seconds,
        arena,
        &path,
        &stats
    );
    
    // Only create path list if we have a valid path
    // Return NULL for no path found (fixes memory leak)
    if (result != GS_SUCCESS || !path) {
        gs_arena_destroy(arena);
        return NULL;
    }
    
    // Create path list result for successful path
    GraphserverPathList* path_list = gs_pathlist_create();
    if (!path_list) {
        gs_path_destroy(path);
        gs_arena_destroy(arena);
        return NULL;
    }
    
    // Expand path list capacity and add the path
    path_list->capacity = 1;
    path_list->paths = malloc(sizeof(GraphserverPath*) * path_list->capacity);
    if (!path_list->paths) {
        gs_path_destroy(path);
        gs_pathlist_destroy(path_list);
        gs_arena_destroy(arena);
        return NULL;
    }
    
    path_list->paths[0] = path;
    path_list->num_paths = 1;
    
    // Merge planner stats with existing engine stats (preserving precaching stats)
    engine->last_plan_stats.vertices_expanded = stats.vertices_expanded;
    // Keep existing cache stats and add any new ones from planning
    engine->last_plan_stats.cache_hits += stats.cache_hits;
    engine->last_plan_stats.cache_misses += stats.cache_misses;
    engine->last_plan_stats.cache_puts += stats.cache_puts;
    engine->last_plan_stats.providers_called += stats.providers_called;
    engine->last_plan_stats.edges_generated += stats.edges_generated;
    
    if (out_stats) {
        *out_stats = stats;
    }
    
    gs_arena_destroy(arena);
    return path_list;
}

GraphserverPath* gs_plan_simple(
    GraphserverEngine* engine,
    const GraphserverVertex* start_vertex,
    gs_goal_predicate_fn is_goal,
    void* goal_user_data,
    GraphserverPlanStats* out_stats) {
    
    if (!engine || !start_vertex || !is_goal) return NULL;
    
    // Create arena for planning operations
    GraphserverArena* arena = gs_arena_create(engine->config.default_arena_size);
    if (!arena) return NULL;
    
    GraphserverPath* path = NULL;
    GraphserverPlanStats stats = {0};
    
    // Use Dijkstra planner directly
    GraphserverResult result = gs_plan_dijkstra(
        engine,
        start_vertex,
        is_goal,
        goal_user_data,
        engine->config.default_timeout_seconds,
        arena,
        &path,
        &stats
    );
    
    // Merge planner stats with existing engine stats (preserving precaching stats)
    engine->last_plan_stats.vertices_expanded = stats.vertices_expanded;
    // Keep existing cache stats and add any new ones from planning
    engine->last_plan_stats.cache_hits += stats.cache_hits;
    engine->last_plan_stats.cache_misses += stats.cache_misses;
    engine->last_plan_stats.cache_puts += stats.cache_puts;
    engine->last_plan_stats.providers_called += stats.providers_called;
    engine->last_plan_stats.edges_generated += stats.edges_generated;
    
    if (out_stats) {
        *out_stats = stats;
    }
    
    gs_arena_destroy(arena);
    
    if (result == GS_SUCCESS) {
        return path;
    } else {
        if (path) gs_path_destroy(path);
        return NULL;
    }
}

GraphserverPath* gs_plan_with_planner(
    GraphserverEngine* engine,
    const GraphserverVertex* start_vertex,
    gs_goal_predicate_fn is_goal,
    void* goal_user_data,
    const char* planner_name,
    GraphserverPlanStats* out_stats) {
    
    if (!engine || !start_vertex || !is_goal || !planner_name) return NULL;
    
    // Create arena for planning operations
    GraphserverArena* arena = gs_arena_create(engine->config.default_arena_size);
    if (!arena) return NULL;
    
    GraphserverPath* path = NULL;
    GraphserverPlanStats stats = {0};
    GraphserverResult result = GS_ERROR_INVALID_ARGUMENT;
    
    if (strcmp(planner_name, "dijkstra") == 0) {
        // Use Dijkstra planner
        result = gs_plan_dijkstra(
            engine,
            start_vertex,
            is_goal,
            goal_user_data,
            engine->config.default_timeout_seconds,
            arena,
            &path,
            &stats
        );
    } else if (strcmp(planner_name, "astar") == 0) {
        // Use A* planner with geographic heuristic
        result = gs_plan_astar(
            engine,
            start_vertex,
            is_goal,
            goal_user_data,
            geographic_distance_heuristic,
            goal_user_data, // Use same goal data for heuristic
            engine->config.default_timeout_seconds,
            arena,
            &path,
            &stats
        );
    }
    
    // Merge planner stats with existing engine stats
    engine->last_plan_stats.vertices_expanded = stats.vertices_expanded;
    engine->last_plan_stats.cache_hits += stats.cache_hits;
    engine->last_plan_stats.cache_misses += stats.cache_misses;
    engine->last_plan_stats.cache_puts += stats.cache_puts;
    engine->last_plan_stats.providers_called += stats.providers_called;
    engine->last_plan_stats.edges_generated += stats.edges_generated;
    
    if (out_stats) {
        *out_stats = stats;
    }
    
    gs_arena_destroy(arena);
    
    if (result == GS_SUCCESS) {
        return path;
    } else {
        if (path) gs_path_destroy(path);
        return NULL;
    }
}

// Utility functions
const char* gs_get_error_message(GraphserverResult result) {
    switch (result) {
        case GS_SUCCESS: return "Success";
        case GS_ERROR_NULL_POINTER: return "Null pointer";
        case GS_ERROR_INVALID_ARGUMENT: return "Invalid argument";
        case GS_ERROR_OUT_OF_MEMORY: return "Out of memory";
        case GS_ERROR_KEY_NOT_FOUND: return "Key not found";
        case GS_ERROR_TYPE_MISMATCH: return "Type mismatch";
        case GS_ERROR_TIMEOUT: return "Timeout";
        case GS_ERROR_NO_PATH_FOUND: return "No path found";
        default: return "Unknown error";
    }
}

const char* gs_get_version(void) {
    return "2.0.0";
}

GraphserverResult gs_initialize(void) {
    // Currently no global initialization needed
    return GS_SUCCESS;
}

void gs_cleanup(void) {
    // Currently no global cleanup needed
}

// Forward declaration for BFS precaching helper
static GraphserverResult bfs_precache(
    GraphserverEngine* engine,
    Provider* provider,
    GraphserverVertex** seed_vertices,
    size_t num_seeds,
    size_t max_depth,
    size_t max_vertices
);

// Edge list node for tracking edge lists to destroy
typedef struct EdgeListNode {
    GraphserverEdgeList* edges;
    struct EdgeListNode* next;
} EdgeListNode;

// BFS precaching state structure
typedef struct {
    PriorityQueue* queue;
    VertexSet* visited;
    GraphserverArena* arena;
    size_t vertices_discovered;
    size_t max_depth;
    size_t max_vertices;
    EdgeListNode* edge_lists_to_destroy;  // Linked list of edge lists to destroy at end
} BFSPrecacheState;

// Pre-cache a subgraph using breadth-first discovery
GraphserverResult gs_engine_precache_subgraph(
    GraphserverEngine* engine,
    const char* provider_name,
    GraphserverVertex** seed_vertices,
    size_t num_seeds,
    size_t max_depth,
    size_t max_vertices) {
    
    // 1. Validate inputs
    if (!engine || !provider_name || !seed_vertices || num_seeds == 0) {
        return GS_ERROR_NULL_POINTER;
    }
    
    // 2. Find provider
    Provider* provider = find_provider(engine, provider_name);
    if (!provider) {
        return GS_ERROR_KEY_NOT_FOUND;
    }
    
    // 3. Check if provider is enabled
    if (!provider->is_enabled) {
        return GS_ERROR_INVALID_ARGUMENT;
    }
    
    // 4. Check edge caching is enabled
    if (!engine->config.enable_edge_caching || !engine->edge_cache) {
        return GS_ERROR_INVALID_ARGUMENT;
    }
    
    // 5. Perform BFS using priority queue
    return bfs_precache(
        engine,
        provider,
        seed_vertices,
        num_seeds,
        max_depth,
        max_vertices
    );
}

// Helper: Initialize BFS precaching state
static GraphserverResult bfs_precache_init_state(
    BFSPrecacheState* state,
    GraphserverEngine* engine,
    GraphserverVertex** seed_vertices,
    size_t num_seeds,
    size_t max_depth,
    size_t max_vertices) {
    
    // Initialize fields
    state->vertices_discovered = 0;
    state->max_depth = max_depth;
    state->max_vertices = max_vertices;
    state->edge_lists_to_destroy = NULL;
    
    // Create arena for BFS operations
    state->arena = gs_arena_create(engine->config.default_arena_size);
    if (!state->arena) {
        return GS_ERROR_OUT_OF_MEMORY;
    }
    
    // Use priority queue with depth as priority for BFS ordering
    state->queue = pq_create(state->arena);
    if (!state->queue) {
        gs_arena_destroy(state->arena);
        return GS_ERROR_OUT_OF_MEMORY;
    }
    
    // Use hash table (vertex set) for visited tracking
    state->visited = vertex_set_create(state->arena);
    if (!state->visited) {
        gs_arena_destroy(state->arena);
        return GS_ERROR_OUT_OF_MEMORY;
    }
    
    // Initialize with seed vertices at depth 0
    for (size_t i = 0; i < num_seeds; i++) {
        if (!pq_insert(state->queue, seed_vertices[i], 0.0)) {
            gs_arena_destroy(state->arena);
            return GS_ERROR_OUT_OF_MEMORY;
        }
    }
    
    return GS_SUCCESS;
}

// Helper: Add edge list to be destroyed later
static void bfs_precache_defer_edge_list_destruction(
    BFSPrecacheState* state,
    GraphserverEdgeList* edges) {
    
    if (!edges) return;
    
    // Allocate node using arena if available, otherwise malloc
    EdgeListNode* node;
    if (state->arena) {
        node = gs_arena_alloc_type(state->arena, EdgeListNode);
    } else {
        node = malloc(sizeof(EdgeListNode));
    }
    
    if (node) {
        node->edges = edges;
        node->next = state->edge_lists_to_destroy;
        state->edge_lists_to_destroy = node;
    } else {
        // If we can't defer destruction, destroy immediately (not ideal but safe)
        gs_edge_list_destroy(edges);
    }
}

// Helper: Queue neighbors from an edge list
static GraphserverResult bfs_precache_queue_neighbors(
    BFSPrecacheState* state,
    GraphserverEdgeList* edges,
    double current_depth) {
    
    size_t edge_count = gs_edge_list_get_count(edges);
    
    for (size_t i = 0; i < edge_count; i++) {
        GraphserverEdge* edge;
        GraphserverResult get_result = gs_edge_list_get_edge(edges, i, &edge);
        
        if (get_result == GS_SUCCESS && edge) {
            GraphserverVertex* dest = gs_edge_get_target_vertex(edge);
            
            if (dest && !vertex_set_contains(state->visited, dest)) {
                if (!pq_insert(state->queue, dest, current_depth + 1.0)) {
                    return GS_ERROR_OUT_OF_MEMORY;
                }
            }
        }
    }
    
    return GS_SUCCESS;
}

// Helper: Process edges that are already cached
static GraphserverResult bfs_precache_process_cached_edges(
    BFSPrecacheState* state,
    GraphserverEdgeList* cached_edges,
    double current_depth) {
    
    // Only queue neighbors if within depth limit
    if (state->max_depth == 0 || current_depth < (double)state->max_depth) {
        return bfs_precache_queue_neighbors(state, cached_edges, current_depth);
    }
    
    return GS_SUCCESS;
}

// Helper: Generate and cache edges for a vertex
static GraphserverEdgeList* bfs_precache_generate_and_cache_edges(
    GraphserverEngine* engine,
    Provider* provider,
    GraphserverVertex* vertex) {
    
    GraphserverEdgeList* edges = gs_edge_list_create();
    if (!edges) {
        return NULL;
    }
    
    // Set the edge list to own its edges so they get properly destroyed
    gs_edge_list_set_owns_edges(edges, true);
    
    // Call provider to generate edges
    int provider_result = provider->outgoing_generator ? 
        provider->outgoing_generator(vertex, edges, provider->user_data) : -1;
    
    if (provider_result == 0) { // Success
        size_t edge_count = gs_edge_list_get_count(edges);
        
        // Only cache non-empty edge lists to avoid corrupting cache with empty data
        if (edge_count > 0) {
            edge_cache_put(engine->edge_cache, vertex, edges);
            engine->last_plan_stats.cache_puts++;
        }
        
        // Update statistics
        engine->last_plan_stats.providers_called++;
        engine->last_plan_stats.edges_generated += edge_count;
        
        // Return edges even if empty (for BFS processing), but don't cache empty lists
        return edges;
    }
    
    // Provider failed - clean up
    gs_edge_list_destroy(edges);
    return NULL;
}

// Helper: Process a single vertex during BFS
static GraphserverResult bfs_precache_process_vertex(
    BFSPrecacheState* state,
    GraphserverEngine* engine,
    Provider* provider,
    GraphserverVertex* vertex,
    double depth) {
    
    // Check if vertex is already cached
    GraphserverEdgeList* cached_edges = NULL;
    GraphserverResult cache_result = edge_cache_get(engine->edge_cache, vertex, &cached_edges);
    
    if (cache_result == GS_SUCCESS && cached_edges) {
        // Already cached - use cached edges for expansion
        GraphserverResult result = bfs_precache_process_cached_edges(state, cached_edges, depth);
        
        // Update cache hit statistics
        engine->last_plan_stats.cache_hits++;
        
        // Defer destruction of cached edges until BFS is complete
        bfs_precache_defer_edge_list_destruction(state, cached_edges);
        return result;
    } else {
        // Not cached - generate and cache edges
        if (cache_result == GS_ERROR_KEY_NOT_FOUND) {
            // Track cache miss
            engine->last_plan_stats.cache_misses++;
        }
        
        GraphserverEdgeList* edges = bfs_precache_generate_and_cache_edges(engine, provider, vertex);
        if (!edges) {
            return GS_SUCCESS; // Provider failed, but continue BFS
        }
        
        // Add neighbors to queue if within depth limit
        GraphserverResult result = GS_SUCCESS;
        if (state->max_depth == 0 || depth < (double)state->max_depth) {
            result = bfs_precache_queue_neighbors(state, edges, depth);
        }
        
        // Defer destruction of edges until BFS is complete
        bfs_precache_defer_edge_list_destruction(state, edges);
        return result;
    }
}

// BFS implementation using priority queue for precaching
static GraphserverResult bfs_precache(
    GraphserverEngine* engine,
    Provider* provider,
    GraphserverVertex** seed_vertices,
    size_t num_seeds,
    size_t max_depth,
    size_t max_vertices) {
    
    // Initialize BFS state
    BFSPrecacheState state;
    GraphserverResult result = bfs_precache_init_state(
        &state, engine, seed_vertices, num_seeds, max_depth, max_vertices);
    
    if (result != GS_SUCCESS) {
        return result;
    }
    
    GraphserverResult overall_result = GS_SUCCESS;
    
    // Main BFS loop
    while (!pq_is_empty(state.queue) && 
           (state.max_vertices == 0 || state.vertices_discovered < state.max_vertices)) {
        
        GraphserverVertex* vertex;
        double depth;
        
        // Get next vertex from queue
        if (!pq_extract_min(state.queue, &vertex, &depth)) {
            break; // Queue is empty
        }
        
        // Skip if already visited
        if (vertex_set_contains(state.visited, vertex)) {
            continue;
        }
        
        // Mark as visited
        if (!vertex_set_add(state.visited, vertex)) {
            overall_result = GS_ERROR_OUT_OF_MEMORY;
            break;
        }
        
        state.vertices_discovered++;
        
        // Update vertices expanded count
        engine->last_plan_stats.vertices_expanded++;
        
        // Process the vertex
        result = bfs_precache_process_vertex(&state, engine, provider, vertex, depth);
        if (result != GS_SUCCESS) {
            overall_result = result;
            break;
        }
    }
    
    // Cleanup: destroy all deferred edge lists
    EdgeListNode* node = state.edge_lists_to_destroy;
    while (node) {
        gs_edge_list_destroy(node->edges);
        EdgeListNode* next = node->next;
        if (!state.arena) {
            free(node);
        }
        node = next;
    }
    
    // Cleanup arena (this also frees EdgeListNodes if allocated with arena)
    gs_arena_destroy(state.arena);
    
    return overall_result;
}