Pure C interface contract for storage backends. More...

#include <entropic/types/error.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for i_storage_backend.h:

This graph shows which files directly or indirectly include this file:

Typedefs
typedef struct entropic_storage_backend *	entropic_storage_backend_t
	Opaque handle to a storage backend instance.

Functions
ENTROPIC_EXPORT entropic_storage_backend_t	entropic_storage_create (const char *db_path)
	Create a storage backend with SQLite at the given path.

ENTROPIC_EXPORT entropic_error_t	entropic_storage_initialize (entropic_storage_backend_t storage)
	Initialize storage (run migrations, create tables).

ENTROPIC_EXPORT void	entropic_storage_destroy (entropic_storage_backend_t storage)
	Destroy storage and close connections.

ENTROPIC_EXPORT char *	entropic_storage_create_conversation (entropic_storage_backend_t storage, const char title, const char project_path, const char *model_id)
	Create a new conversation.

ENTROPIC_EXPORT entropic_error_t	entropic_storage_save_conversation (entropic_storage_backend_t storage, const char conversation_id, const char messages_json)
	Save messages to a conversation.

ENTROPIC_EXPORT entropic_error_t	entropic_storage_load_conversation (entropic_storage_backend_t storage, const char conversation_id, char *result_json)
	Load a conversation with messages.

ENTROPIC_EXPORT entropic_error_t	entropic_storage_list_conversations (entropic_storage_backend_t storage, int limit, int offset, char **result_json)
	List conversations with pagination.

ENTROPIC_EXPORT entropic_error_t	entropic_storage_search_conversations (entropic_storage_backend_t storage, const char query, int limit, char *result_json)
	Full-text search across conversations.

ENTROPIC_EXPORT entropic_error_t	entropic_storage_delete_conversation (entropic_storage_backend_t storage, const char *conversation_id)
	Delete a conversation and all associated records.

ENTROPIC_EXPORT entropic_error_t	entropic_storage_create_delegation (entropic_storage_backend_t storage, const char parent_conversation_id, const char delegating_tier, const char target_tier, const char task, int max_turns, char **result_json)
	Create a delegation record with a child conversation.

ENTROPIC_EXPORT entropic_error_t	entropic_storage_complete_delegation (entropic_storage_backend_t storage, const char delegation_id, const char status, const char *result_summary)
	Mark a delegation as completed or failed.

ENTROPIC_EXPORT entropic_error_t	entropic_storage_get_delegations (entropic_storage_backend_t storage, const char conversation_id, char *result_json)
	Get delegations for a parent conversation.

ENTROPIC_EXPORT entropic_error_t	entropic_storage_save_snapshot (entropic_storage_backend_t storage, const char conversation_id, const char messages_json)
	Save a pre-compaction snapshot of full conversation history.

ENTROPIC_EXPORT entropic_error_t	entropic_storage_get_stats (entropic_storage_backend_t storage, char **result_json)
	Get storage statistics.

Detailed Description

Pure C interface contract for storage backends.

Defines the .so boundary for librentropic-storage. All functions accept/return C types only (opaque handles, const char*, error codes). No C++ types cross this boundary.

Storage is fully optional. NULL handle checks are the consumer's responsibility — passing NULL to any function returns an error code.

Version: 1.8.8

Definition in file i_storage_backend.h.

Typedef Documentation

◆ entropic_storage_backend_t

typedef struct entropic_storage_backend* entropic_storage_backend_t

Opaque handle to a storage backend instance.

Definition at line 28 of file i_storage_backend.h.

Function Documentation

◆ entropic_storage_complete_delegation()

ENTROPIC_EXPORT entropic_error_t entropic_storage_complete_delegation	(	entropic_storage_backend_t	storage,
		const char *	delegation_id,
		const char *	status,
		const char *	result_summary
	)

Mark a delegation as completed or failed.

Parameters

storage	Storage handle.
delegation_id	Delegation ID.
status	"completed" or "failed".
result_summary	Summary text or NULL.

Returns: ENTROPIC_OK on success.

Version: 1.8.8

Mark a delegation as completed or failed.

Parameters

storage	Handle.
delegation_id	Delegation ID.
status	Status string.
result_summary	Optional summary.

Returns: Error code.

Definition at line 333 of file c_interface.cpp.

◆ entropic_storage_create()

ENTROPIC_EXPORT entropic_storage_backend_t entropic_storage_create ( const char * db_path )

Create a storage backend with SQLite at the given path.

Parameters

db_path Path to SQLite database file. Created if absent.

Returns: Storage handle, or NULL on failure.

Version: 1.8.8

Create a storage backend with SQLite at the given path.

Parameters

db_path Database file path.

Returns: Handle or NULL.

Definition at line 80 of file c_interface.cpp.

◆ entropic_storage_create_conversation()

ENTROPIC_EXPORT char * entropic_storage_create_conversation	(	entropic_storage_backend_t	storage,
		const char *	title,
		const char *	project_path,
		const char *	model_id
	)

Create a new conversation.

Parameters

storage	Storage handle.
title	Conversation title (null-terminated).
project_path	Project path or NULL.
model_id	Model identifier or NULL.

Returns: Conversation ID string. Caller must free with entropic_free(). NULL on failure.

Version: 1.8.8

Create a new conversation.

Parameters

storage	Handle.
title	Title.
project_path	Optional project path.
model_id	Optional model ID.

Returns: Conversation ID (caller frees) or NULL.

Definition at line 131 of file c_interface.cpp.

◆ entropic_storage_create_delegation()

ENTROPIC_EXPORT entropic_error_t entropic_storage_create_delegation	(	entropic_storage_backend_t	storage,
		const char *	parent_conversation_id,
		const char *	delegating_tier,
		const char *	target_tier,
		const char *	task,
		int	max_turns,
		char **	result_json
	)

Create a delegation record with a child conversation.

Parameters

storage	Storage handle.
parent_conversation_id	Parent conversation ID.
delegating_tier	Tier initiating delegation.
target_tier	Target tier for child loop.
task	Task description.
max_turns	Max turns for child (0 for unlimited).
result_json	Output: JSON with "delegation_id" and "child_conversation_id". Caller must free.

Returns: ENTROPIC_OK on success.

Version: 1.8.8

Create a delegation record with a child conversation.

Parameters

storage	Handle.
parent_conversation_id	Parent conversation.
delegating_tier	Source tier.
target_tier	Target tier.
task	Task description.
max_turns	Turn limit.
result_json	Output JSON.

Returns: Error code.

Definition at line 294 of file c_interface.cpp.

◆ entropic_storage_delete_conversation()

ENTROPIC_EXPORT entropic_error_t entropic_storage_delete_conversation	(	entropic_storage_backend_t	storage,
		const char *	conversation_id
	)

Delete a conversation and all associated records.

Parameters

storage	Storage handle.
conversation_id	Conversation ID.

Returns: ENTROPIC_OK on success.

Version: 1.8.8

Delete a conversation and all associated records.

Parameters

storage	Handle.
conversation_id	Conversation ID.

Returns: Error code.

Definition at line 264 of file c_interface.cpp.

◆ entropic_storage_destroy()

ENTROPIC_EXPORT void entropic_storage_destroy ( entropic_storage_backend_t storage )

Destroy storage and close connections.

Parameters

storage Storage handle (NULL-safe).

Version: 1.8.8

Destroy storage and close connections.

Parameters

storage Handle (NULL-safe).

Definition at line 115 of file c_interface.cpp.

◆ entropic_storage_get_delegations()

ENTROPIC_EXPORT entropic_error_t entropic_storage_get_delegations	(	entropic_storage_backend_t	storage,
		const char *	conversation_id,
		char **	result_json
	)

Get delegations for a parent conversation.

Parameters

storage	Storage handle.
conversation_id	Parent conversation ID.
result_json	Output: JSON array of delegation records. Caller must free.

Returns: ENTROPIC_OK on success.

Version: 1.8.8

Get delegations for a parent conversation.

Parameters

storage	Handle.
conversation_id	Parent conversation.
result_json	Output JSON.

Returns: Error code.

Definition at line 360 of file c_interface.cpp.

◆ entropic_storage_get_stats()

ENTROPIC_EXPORT entropic_error_t entropic_storage_get_stats	(	entropic_storage_backend_t	storage,
		char **	result_json
	)

Get storage statistics.

Parameters

storage	Storage handle.
result_json	Output: JSON with total_conversations, total_messages, total_tokens. Caller must free.

Returns: ENTROPIC_OK on success.

Version: 1.8.8

Get storage statistics.

Parameters

storage	Handle.
result_json	Output JSON.

Returns: Error code.

Definition at line 415 of file c_interface.cpp.

◆ entropic_storage_initialize()

ENTROPIC_EXPORT entropic_error_t entropic_storage_initialize ( entropic_storage_backend_t storage )

Initialize storage (run migrations, create tables).

Parameters

storage Storage handle.

Returns: ENTROPIC_OK on success.

Version: 1.8.8

Initialize storage (run migrations, create tables).

Parameters

storage Handle.

Returns: Error code.

Definition at line 98 of file c_interface.cpp.

◆ entropic_storage_list_conversations()

ENTROPIC_EXPORT entropic_error_t entropic_storage_list_conversations	(	entropic_storage_backend_t	storage,
		int	limit,
		int	offset,
		char **	result_json
	)

List conversations with pagination.

Parameters

storage	Storage handle.
limit	Max results.
offset	Pagination offset.
result_json	Output: JSON array of conversation summaries. Caller must free with entropic_free().

Returns: ENTROPIC_OK on success.

Version: 1.8.8

List conversations with pagination.

Parameters

storage	Handle.
limit	Max results.
offset	Offset.
result_json	Output JSON.

Returns: Error code.

Definition at line 210 of file c_interface.cpp.

◆ entropic_storage_load_conversation()

ENTROPIC_EXPORT entropic_error_t entropic_storage_load_conversation	(	entropic_storage_backend_t	storage,
		const char *	conversation_id,
		char **	result_json
	)

Load a conversation with messages.

Parameters

storage	Storage handle.
conversation_id	Conversation ID.
result_json	Output: JSON with "conversation" and "messages". Caller must free with entropic_free().

Returns: ENTROPIC_OK on success, ENTROPIC_ERROR_INVALID_ARGUMENT if not found.

Version: 1.8.8

Load a conversation with messages.

Parameters

storage	Handle.
conversation_id	Conversation ID.
result_json	Output JSON.

Returns: Error code.

Definition at line 181 of file c_interface.cpp.

◆ entropic_storage_save_conversation()

ENTROPIC_EXPORT entropic_error_t entropic_storage_save_conversation	(	entropic_storage_backend_t	storage,
		const char *	conversation_id,
		const char *	messages_json
	)

Save messages to a conversation.

Parameters

storage	Storage handle.
conversation_id	Conversation ID.
messages_json	JSON array of message objects.

Returns: ENTROPIC_OK on success.

Version: 1.8.8

Parameters

storage	Handle.
conversation_id	Conversation ID.
messages_json	JSON array.

Returns: Error code.

Definition at line 156 of file c_interface.cpp.

◆ entropic_storage_save_snapshot()

ENTROPIC_EXPORT entropic_error_t entropic_storage_save_snapshot	(	entropic_storage_backend_t	storage,
		const char *	conversation_id,
		const char *	messages_json
	)

Save a pre-compaction snapshot of full conversation history.

Parameters

storage	Storage handle.
conversation_id	Conversation ID.
messages_json	JSON array of all messages before compaction.

Returns: ENTROPIC_OK on success.

Version: 1.8.8

Save a pre-compaction snapshot of full conversation history.

Parameters

storage	Handle.
conversation_id	Conversation ID.
messages_json	JSON messages.

Returns: Error code.

Definition at line 389 of file c_interface.cpp.

◆ entropic_storage_search_conversations()

ENTROPIC_EXPORT entropic_error_t entropic_storage_search_conversations	(	entropic_storage_backend_t	storage,
		const char *	query,
		int	limit,
		char **	result_json
	)

Full-text search across conversations.

Parameters

storage	Storage handle.
query	FTS5 query string.
limit	Max results.
result_json	Output: JSON array of search results with snippets. Caller must free with entropic_free().

Returns: ENTROPIC_OK on success.

Version: 1.8.8

Full-text search across conversations.

Parameters

storage	Handle.
query	FTS5 query.
limit	Max results.
result_json	Output JSON.

Returns: Error code.

Definition at line 238 of file c_interface.cpp.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ entropic_storage_backend_t

Function Documentation

◆ entropic_storage_complete_delegation()

◆ entropic_storage_create()

◆ entropic_storage_create_conversation()

◆ entropic_storage_create_delegation()

◆ entropic_storage_delete_conversation()

◆ entropic_storage_destroy()

◆ entropic_storage_get_delegations()

◆ entropic_storage_get_stats()

◆ entropic_storage_initialize()

◆ entropic_storage_list_conversations()

◆ entropic_storage_load_conversation()

◆ entropic_storage_save_conversation()

◆ entropic_storage_save_snapshot()

◆ entropic_storage_search_conversations()