/**
 * engram.h — C header for the engram FFI.
 *
 * Generated from crates/engram-ffi/src/lib.rs.
 * To regenerate: cargo install cbindgen && cbindgen --crate engram-ffi -o bindings/go/engram.h
 *
 * Build the shared library:
 *   cargo build --package engram-ffi --release
 *   # macOS: target/release/libengram_ffi.dylib
 *   # Linux: target/release/libengram_ffi.so
 */
#pragma once

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/** Opaque handle to an open EngramDb. Obtained via engram_open. */
typedef struct EngramHandle EngramHandle;

/** Open or create an engram database at `path`. Returns null on error. */
EngramHandle* engram_open(const char* path);

/** Close and free a database handle. The pointer must not be used afterwards. */
void engram_close(EngramHandle* handle);

/** Return the number of nodes in the database, or -1 on error. */
int64_t engram_node_count(const EngramHandle* handle);

/** Return the number of edges in the database, or -1 on error. */
int64_t engram_edge_count(const EngramHandle* handle);

/**
 * Apply multiplicative salience decay to all nodes.
 * `factor` should be in (0.0, 1.0). Returns nodes updated, or -1 on error.
 */
int64_t engram_decay(EngramHandle* handle, float factor);

/**
 * Store a node from a JSON string.
 * JSON: { "content": "...", "node_type": "Memory", "tier": "Episodic",
 *         "importance": 0.8, "embedding": [f32, ...] }
 * Returns a heap-allocated UUID string on success, null on error.
 * Free with engram_free_string.
 */
char* engram_put_node(EngramHandle* handle, const char* json);

/**
 * Retrieve a node by UUID. Returns a heap-allocated JSON string, or null.
 * Free with engram_free_string.
 */
char* engram_get_node(const EngramHandle* handle, const char* id);

/**
 * Run spreading activation.
 * `req_json`: { "seeds": ["uuid", ...], "query_embedding": [f32, ...],
 *               "max_depth": 3, "limit": 10 }
 * Returns a heap-allocated JSON array, or null on error.
 * Free with engram_free_string.
 */
char* engram_activate(const EngramHandle* handle, const char* req_json);

/** Free a string returned by any engram FFI function. */
void engram_free_string(char* s);

#ifdef __cplusplus
} /* extern "C" */
#endif