API surfaces

C Stable API

Integrate Maelys Datalog through its stable opaque C API and explicit ownership model.

Stable public consumer API · version 2

The stable C API is the recommended integration surface for new native consumers. Policies, prepared sessions and solve results are opaque handles: application code need not depend on parser, ruleset, symbol-table, EDB or solver layouts. Datalog 0.11.1 uses consumer API 2, frontend/program ABI 2, backend ABI 5 and diagnostic ABI 1. Recompile existing C/C++ consumers; removed type aliases have no compatibility layer.

CODE

#include <maelys/datalog.h>

What stable means

The stable boundary covers the declarations in <maelys/datalog.h>, identified by MAELYS_DATALOG_PUBLIC_API_VERSION. Internal structure layouts are not part of that contract.

Guaranteed boundary	Consequence for applications
Opaque policy, session, and result handles	Internal structures may evolve without requiring source access from consumers.
Explicit status values	Every operation reports success or a named fail-closed category.
Explicit ownership	Each successful allocation has one matching `*_free` operation.
Result-scoped symbol rendering	Runtime symbol identifiers are interpreted by the exact result that produced them.
Canonical policy fingerprints	A consumer can bind a loaded policy or session to its engine identity.

The library release version and the public API version are separate concepts. The API version identifies the shape of this facade; the library release identifies a concrete implementation.

For release-by-release changes, see the Changelog.

The lifecycle

1. Register domaindomain_register

Declare the closed predicate vocabulary and allowed source atoms.

2. Load policypolicy_load_*

Parse inline policy text or load a manifest into an opaque policy handle.

3. Create sessionsession_create

Prepare one selected policy for repeated runtime fact sets.

4. Solvesession_solve

Submit one bounded fact array and obtain an immutable result.

5. Inspect resultresult_*

Query facts, enumerate a relation, resolve symbols, or render Why-true or Why-false.

6. Release*_free

Free results first, then their session. A policy may be freed after session creation.

API by responsibility

Responsibility	Operations	Purpose
Domain	domain_register	Install the vocabulary used to validate policy source and runtime facts.
Loading	policy_load_inline · policy_load_manifest	Create an opaque policy from source bytes or a governed manifest.
Identity	policy_fingerprint · session_fingerprint	Read the canonical policy identity before or after selecting a policy.
Session	session_create · session_solve	Prepare one policy once and evaluate independent runtime fact sets.
Queries	result_query · result_enumerate	Check one ground fact or enumerate an already-derived query relation.
Rendering	result_symbol_text · result_explain_true_text · result_explain_false_text	Resolve result-owned symbols and render Why-true or Why-false text.
Lifetime	policy_free · session_free · result_free	Release each opaque object at the end of its documented lifetime.
Input buffer	input_edb_create · input_edb_init · input_edb_add_fact · input_edb_add_facts · session_solve_edb	Copy facts into bounded owned storage and solve from it.
Configuration	session_config_create · session_create_configured · session_execution_fingerprint	Require capabilities or a work budget explicitly and read execution identity.
Limits	limit_get · result_derived_fact_count	Read loaded-library capacities and distinct derived-fact counts.
Prepared explanations	result_explanation_storage_requirements · result_prepare_explanation · prepared_explanation_text_size · prepared_explanation_write_text · prepared_explanation_release	Prepare once in caller-owned storage, measure and write repeatedly, then release.
Optional C builders	MAELYS_DATALOG_EDB · MAELYS_DATALOG_IDB_QUERY · MAELYS_DATALOG_ADD_FACTS · MAELYS_DATALOG_QUERY	Optional source builders; no additional exported symbols or ABI change.

Reference by topic

Choose the stable C operation by task. Each topic links to its separate explanation of the underlying concept.

Topic	C Stable API	Concept
Domain	Registries	Registries
Load	Manifests	Manifests
Policy	Rulesets	Rulesets
Facts	Runtime EDB	EDB
Solve	Solving	Solving
Query	Querying	Querying
Errors	Statuses and diagnostics	Fail-closed outcomes

For a runnable C example, see the Full program. Additional operations on the same opaque handles—including in-memory manifests, dynamic domain registration and structured explanations—are documented in the C Advanced API.

Deliberate boundary

The stable header does not expose parser objects, ruleset fields, EDB pools, symbol-table mutation or solver internals. Use the C Advanced API for supported extensions on the same opaque handles. Its operations live in a separate installed header.

For language semantics, see the Datalog language. For the meaning of the lifecycle stages, see the concept pages on registries, rulesets, runtime EDB, solving, and querying.