Registries

██████╗ ███████╗ ██████╗ ██╗███████╗████████╗██████╗ ██╗███████╗███████╗
██╔══██╗██╔════╝██╔════╝ ██║██╔════╝╚══██╔══╝██╔══██╗██║██╔════╝██╔════╝
██████╔╝█████╗  ██║  ███╗██║███████╗   ██║   ██████╔╝██║█████╗  ███████╗
██╔══██╗██╔══╝  ██║   ██║██║╚════██║   ██║   ██╔══██╗██║██╔══╝  ╚════██║
██║  ██║███████╗╚██████╔╝██║███████║   ██║   ██║  ██║██║███████╗███████║
╚═╝  ╚═╝╚══════╝ ╚═════╝ ╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═╝╚═╝╚══════╝╚══════╝

Registries define the vocabulary a Datalog policy is allowed to use. A Datalog rule can mention predicates such as owns, shared_with, blocked, or allow, but the Datalog engine does not know what these names mean by itself. The application must first declare which predicates exist, how many arguments they accept, and how they may be used.

In Maelys DL, this is a core security boundary:

Domain Registry  =  vocabulary authority
Policy source    =  Datalog logic using that vocabulary
Manifest         =  deployment contract and public observation gate

Why registries exist

A Datalog engine can evaluate rules generically, but applications need their own vocabulary. For example, a document-access application might need:

owns(User, Document)
shared_with(User, Document)
blocked(User)
allow(User, Document)

A graph application might need:

edge(From, To)
reachable(From, To)

A decision engine might need:

safe(Request)
allow(Request)
deny(Request)

The Datalog engine should not hard-code any of these names. Instead, each application registers a domain that declares the predicates policies may use. Registries answer three questions:

Where registries fit

Registries define and freeze the vocabulary before policy loading happens.

Architectural model

Three layers govern how a policy is loaded and evaluated.

Domain Registry
    -> declares what predicates exist and what they can do
Policy source
    -> uses that vocabulary to derive facts
Manifest
    -> selects a domain, verifies source integrity, and exposes only
       whitelisted QUERY predicates

Predicate kinds at a glance

Four kinds are used throughout this page. They are introduced here so the examples that follow are self-explanatory.

Flags may be combined: IDB|QUERY means a predicate is both derived and queryable. The full C definitions and combination rules are in Predicate kinds below.

Domain-closed vocabulary

Maelys DL uses a domain-closed vocabulary model. That means every predicate used by a policy must be accepted by the selected domain. A policy cannot invent predicates during loading, and a manifest cannot add predicates to the domain. For example, this policy:

helper(X) :- safe(X).
allow(X) :- helper(X).

requires the selected domain to declare:

safe/1    EDB
helper/1  IDB
allow/1   IDB|QUERY

If helper/1 is not declared by the domain, loading fails.

Example domain: document access

Suppose an application wants to evaluate document access rules. The application wants this vocabulary:

A policy in this domain might contain:

blocked("mallory").
allow(User, Document) :-
    owns(User, Document),
    not blocked(User),
    sensitivity_level(User, Level),
    Level >= 3.
allow(User, Document) :-
    shared_with(User, Document),
    not blocked(User),
    sensitivity_level(User, Level),
    Level >= 3.

The extra sensitivity_level/2 guard adds a numeric threshold: ownership or sharing alone is not enough, the caller must also meet the minimum level.

In this example:

The application supplies runtime facts such as:

owns("alice", "roadmap.pdf").
shared_with("bob", "roadmap.pdf").
sensitivity_level("alice", 4).
sensitivity_level("bob", 3).

The policy declares policy facts such as:

blocked("mallory").

The solver derives facts such as:

allow("alice", "roadmap.pdf").
allow("bob", "roadmap.pdf").

Both users satisfy the Level >= 3 guard, so the solver still derives allow/2 for each of them. A user with a lower sensitivity level would not derive allow/2 even if the ownership or sharing fact were present.

Whether callers may publicly inspect allow/2 depends on the loading path:

Registry model

Maelys DL uses two related registries.

The domain registry answers:

Which domains are available?

The predicate registry answers:

Which predicates may this policy use?

During loading:

selected domain
    -> installs predicate vocabulary
    -> policy source is validated against that vocabulary

Domain registry

The domain registry stores domain definitions. A domain definition has:

A domain may provide its vocabulary in exactly one of two ways:

The constraint is an XOR:

valid:
  install_predicates != NULL
  predicates == NULL
  predicate_count == 0
valid:
  install_predicates == NULL
  predicates != NULL
  predicate_count > 0
invalid:
  install_predicates != NULL
  predicates != NULL
invalid:
  install_predicates == NULL
  predicates == NULL

Method 1: static predicate table

A fixed domain can declare its predicates as a static table.

static const maelys_datalog_predicate_def_t document_access_predicates[] = {
    {
        .name       = "owns",
        .arity      = 2,
        .kind_flags = MAELYS_DATALOG_PRED_KIND_EDB,
    },
    {
        .name       = "shared_with",
        .arity      = 2,
        .kind_flags = MAELYS_DATALOG_PRED_KIND_EDB,
    },
    {
        .name       = "sensitivity_level",
        .arity      = 2,
        .kind_flags = MAELYS_DATALOG_PRED_KIND_EDB,
    },
    {
        .name       = "blocked",
        .arity      = 1,
        .kind_flags = MAELYS_DATALOG_PRED_KIND_POLICY_FACT,
    },
    {
        .name       = "allow",
        .arity      = 2,
        .kind_flags = MAELYS_DATALOG_PRED_KIND_IDB |
                      MAELYS_DATALOG_PRED_KIND_QUERY,
    },
};
static const maelys_datalog_domain_def_t document_access_domain_def = {
    .domain_name     = "document_access",
    .predicates      = document_access_predicates,
    .predicate_count = sizeof(document_access_predicates) /
                       sizeof(document_access_predicates[0]),
    .description     = "Document access-control policy domain",
};

This form is convenient when the whole vocabulary is known at compile time.

Method 2: installer callback

A domain can also install its predicates through a callback.

static maelys_result_t
install_document_access_predicates(
    maelys_datalog_predicate_registry_t *registry)
{
    maelys_result_t rc;
    rc = maelys_datalog_predicate_registry_add_domain(
        registry,
        "owns",
        2,
        MAELYS_DATALOG_PRED_KIND_EDB);
    if (rc != MAELYS_OK) {
        return rc;
    }
    rc = maelys_datalog_predicate_registry_add_domain(
        registry,
        "shared_with",
        2,
        MAELYS_DATALOG_PRED_KIND_EDB);
    if (rc != MAELYS_OK) {
        return rc;
    }
    rc = maelys_datalog_predicate_registry_add_domain(
        registry,
        "sensitivity_level",
        2,
        MAELYS_DATALOG_PRED_KIND_EDB);
    if (rc != MAELYS_OK) {
        return rc;
    }
    rc = maelys_datalog_predicate_registry_add_domain(
        registry,
        "blocked",
        1,
        MAELYS_DATALOG_PRED_KIND_POLICY_FACT);
    if (rc != MAELYS_OK) {
        return rc;
    }
    return maelys_datalog_predicate_registry_add_domain(
        registry,
        "allow",
        2,
        MAELYS_DATALOG_PRED_KIND_IDB |
        MAELYS_DATALOG_PRED_KIND_QUERY);
}
static const maelys_datalog_domain_def_t document_access_domain_def = {
    .domain_name        = "document_access",
    .predicates         = NULL,
    .predicate_count    = 0,
    .description        = "Document access-control policy domain",
    .install_predicates = install_document_access_predicates,
};

predicates = NULL and predicate_count = 0 indicate the callback path. This form is useful when predicates come from multiple C modules, require conditional installation, or need shared setup logic.

Registering a domain

A domain is registered globally with:

maelys_datalog_domain_registry_register(&document_access_domain_def);

The global domain registry uses first-registration-wins semantics. If a domain name is already registered, subsequent calls with the same name are silently ignored and return MAELYS_OK. The originally registered domain remains authoritative for the lifetime of the process.

Once registered, the domain is available to all loading paths by name. A manifest references it through the domain field:

{
  "domain": "document_access"
}

An inline load passes the domain name as the first argument to maelys_datalog_load_policy_inline. See Inline loading for the full call signature and semantics.

Predicate registry

The predicate registry contains the predicates available to one loaded policy. A predicate declaration defines:

Example:

maelys_datalog_predicate_registry_add_domain(
    registry,
    "allow",
    2,
    MAELYS_DATALOG_PRED_KIND_IDB |
    MAELYS_DATALOG_PRED_KIND_QUERY);

This declaration means:

allow/2 exists
allow/2 is derived by Datalog rules
allow/2 is capable of being queried

It does not mean allow/2 is publicly observable for every manifest-loaded deployment. Manifest-loaded policies still require allow/2 to be listed in the Public Query Whitelist.

Predicate identity: one name, one arity

A predicate name expresses a unique relation with a fixed arity. The registry enforces this as an identity contract: once owns is declared with arity 2, no other declaration of owns with a different arity is accepted.

owns/2  EDB   ✓  — the relation "user owns document"
edge/1  EDB   ✓  — the relation "node exists"
edge/2  EDB   ✗  — rejected: "edge" already has arity 1

If the semantic relationship changes arity, the predicate must change name:

edge/1          node-exists relation
link/2          two-node relation  — different name, different concept

The registry returns MAELYS_ERR_INVALID_FIELD if the same name is registered with two different arities. This is by design: the name of a predicate is the contract of the relation it represents. Allowing the same name to mean two different structural relations — one with one argument, one with two — would make policy rules ambiguous and solver results unpredictable.

Registry lifecycle: open, then frozen

The predicate registry has exactly two states. When a ruleset is initialized the registry is open: predicates may be added through maelys_datalog_predicate_registry_add_domain (or by installing a domain). Once the vocabulary is complete it is frozen, and the policy source is parsed and validated against that frozen vocabulary. Freezing is the point of no return: no predicate may be added after it.

The red branch is the security property in visual form: once the registry is frozen, any further attempt to add a predicate is refused. The vocabulary a policy may use is sealed before a single line of policy source is parsed.

void
maelys_datalog_predicate_registry_freeze(
    maelys_datalog_predicate_registry_t *registry);

In the manual ruleset pipeline, freeze sits between domain installation and parsing:

/* Open registry: install the domain vocabulary */
maelys_datalog_predicate_registry_add_domain(
    &ruleset.registry, "owns",    2, MAELYS_DATALOG_PRED_KIND_EDB);
maelys_datalog_predicate_registry_add_domain(
    &ruleset.registry, "blocked", 1, MAELYS_DATALOG_PRED_KIND_POLICY_FACT);
maelys_datalog_predicate_registry_add_domain(
    &ruleset.registry, "allow",   2,
    MAELYS_DATALOG_PRED_KIND_IDB | MAELYS_DATALOG_PRED_KIND_QUERY);
 
/* Freeze: no predicates may be added after this point */
maelys_datalog_predicate_registry_freeze(&ruleset.registry);
 
/* Parse: validated against the frozen vocabulary */
maelys_datalog_parse_ruleset_ex(&ruleset, src, src_len, file_path, &diag);

Predicate kinds

A predicate may combine flags:

MAELYS_DATALOG_PRED_KIND_IDB |
MAELYS_DATALOG_PRED_KIND_QUERY

This means the predicate is derived by the solver and has query capability. For manifest-loaded policies, public visibility is still controlled by the manifest Public Query Whitelist.

Loading paths

Once a domain is registered, it is available to both loading paths. The path chosen determines whether the QUERY predicates declared by the domain are subject to a Public Query Whitelist.

Manifest path — the manifest selects the registered domain, verifies policy source integrity, and enforces a Public Query Whitelist through its queries field. Only predicates explicitly listed there are publicly observable after solving. See Manifest loading for the full model.

Inline path — the domain name is passed directly to maelys_datalog_load_policy_inline or maelys_datalog_load_policy_inline_with_static_domain. There is no manifest and no Public Query Whitelist: all predicates declared as QUERY by the selected domain are accessible. See Manifest loading — Inline loading for the full call signature.

Domain registration in WASM

The domain registration model is the same in WASM and C. How you load the domain depends on which loading strategy you use.

Dynamic target — domain defined in JavaScript

With maelys_datalog_dynamic.js, the domain is defined at runtime from JavaScript using the dynamic builder. No C code is needed.

pg.domainBegin('access')
pg.domainAddPredicate('safe',  1, PredKind.EDB)
pg.domainAddPredicate('allow', 1, PredKind.IDB | PredKind.QUERY)
pg.domainCommit()

This corresponds to the static-table model but called from JavaScript. The predicate vocabulary is registered inside the WASM module. One domain per module instance — domainCommit() is permanent.

Under the hood, the dynamic builder accumulates the domain definition in a WASM-side static buffer, then makes the same core registration call as the static-table model above — it is not a separate registration mechanism. Only domainCommit enters the core engine:

In other words, domainBegin and domainAddPredicate build, in WASM-module memory, the exact predicate table shown in Method 1: static predicate table — the runtime equivalent of writing that static table, which in C is a compile-time artifact, not a function call. The single core-engine entry point is domainCommit, which performs the same domain registration call (maelys_datalog_domain_registry_register) that C code would make directly. The vocabulary, kind flags, arity contract, and first-registration-wins semantics are therefore identical; only the call site differs (JavaScript instead of C).

See WASM bindings — Dynamic builder.

Production target — domain table compiled in C

This target is a two-faced model. In it, JavaScript does not build the domain: the domain table is C code compiled into the WASM module. JavaScript only calls the exported loader for that fixed domain. The C face declares the vocabulary; the JS face just hands a policy source to a single export.

The C face — the same static table as Method 1, plus one exported loader:

static const maelys_datalog_predicate_def_t preds[] = {
    { "owns",  2, MAELYS_DATALOG_PRED_KIND_EDB },
    { "allow", 2, MAELYS_DATALOG_PRED_KIND_IDB |
                  MAELYS_DATALOG_PRED_KIND_QUERY },
};
 
EMSCRIPTEN_KEEPALIVE
maelys_result_t load_document_access(const char *src, size_t src_len) {
    return maelys_datalog_load_policy_inline_with_static_domain(
        preds, 2, "document_access", "doc.main",
        src, src_len, 0, &g_policy, &g_diag);
}

This is the static-table approach compiled into the WASM binary. The domain is fixed; the policy source can be fetched at runtime. The JavaScript side should normally call this through a small application wrapper rather than raw ccall; see the WASM static-domain strategy for the full loader.

Loading API comparison

Manifest APIs — require explicit domain registration before load, enforce a Public Query Whitelist.

Inline APIs — no manifest, no whitelist. All domain QUERY predicates accessible.

Validation behavior

Summary