API surfaces

C Advanced API

Additional operations on the stable opaque C handles, introduced in Datalog 0.10.0.

CODE

#include <maelys/datalog.h>
#include <maelys/datalog_advanced.h>

The public consumer contract is API 2. Frontend and program descriptors use ABI 2, backend descriptors use ABI 5, and diagnostics use ABI 1. These numbers describe different boundaries; none is the Datalog language version.

Reference by theme

Start with the advanced operation your application needs. The Stable API still supplies the core domain, policy, EDB, solve, query and cleanup calls.

Theme	What Advanced adds
Domain builders	Register a domain whose predicate declarations are installed by a callback at policy load.
Manifest bundles	Load verified manifest JSON and policy source bytes entirely from memory.
Policy storage	Give the loader aligned memory for the policy object, without claiming a zero-allocation load.
Session configuration	Select a backend or context, attach backend preparation storage, and require capabilities or a work budget.
Structured explanations	Read Why-true steps and Why-false obstacles from an existing prepared explanation.
Decisions and statistics	Inspect reference-backend filter work or combine three queried presence values.
Event windows	Retain bounded native event snapshots with separately installed adapter headers.

There is no second Advanced EDB API: the stable input EDB works with these same handles. Statuses and diagnostics use the stable error model; individual pages call out their additional failure cases. The installed <maelys/datalog_details.h> supplies shared semantic enums and view records, not a second diagnostic or fact representation.

Loading architectures

The installed SDK has three working loading paths and one historical shape that is not exposed. Advanced C uses both headers: it inherits stable file-manifest and registered-domain inline loading, then adds the in-memory manifest-bundle call.

Path	Variant	Stable C	Advanced C
Manifest	files on disk	✓	✓
Manifest	JSON and source in memory	✕	✓
Inline	source bytes; registered domain	✓	✓
Inline	register domain + load source in one call	✕	✕

The diagram separates where policy bytes come from from how the domain vocabulary is supplied:

Domain vocabulary

registered before loading in the installed API

Manifest · file

Verified files
stable · policy_load_manifest

Manifest · buffer

JSON + policy bytes
advanced · policy_load_manifest_text

Inline · registered

One policy source
stable · policy_load_inline

Inline · combined (historical)

The file manifest reads JSON and sources from disk. The buffer manifest keeps policy-set metadata, SHA-256 checks and the Public Query Whitelist while accepting the bytes in memory. The registered-domain inline path takes one raw source without a manifest or whitelist. All three require domain registration beforehand.

Static predicate tables are supported, in Stable and Advanced C. Register the maelys_datalog_domain_t declaration, including its source atoms, then use maelys_datalog_policy_load_inline(). Registration copies the declarations into the global registry; a static table is not a no-copy loading path. Register once to share the vocabulary across several policies. Inline loading consumes source bytes entirely in memory, with no filesystem access.

The historical one-call static-table loader is in neither installed header. It registered a domain first, then loaded a policy: if loading failed, the domain remained registered. That combined operation was not atomic. The installed SDK keeps these two operations explicit and does not offer a combined call. Its registered-domain loading paths do not provide an autonomous policy-local vocabulary: registration changes the global registry even if a subsequent load fails.

The WASM binding likewise uses registerDomain(), then loadPolicy(). Combining the two existing JavaScript methods would still perform their two conversions and native calls; it does not establish a performance gain. For ordinary applications that need none of the extensions above, begin with the C Stable API.