C Advanced API

Decisions and statistics

Inspect reference-backend filter work and combine queried presence into an explicit decision.

The stable query API tells you whether a fact was derived. These advanced operations answer two different follow-up questions: how many filter evaluations happened during solving, and what final decision follows from three already-queried presence values. Neither operation solves or queries a policy for you.

Types

Defined on this page

Type	Purpose
`maelys_datalog_filter_statistics_t`	Counts filter evaluation work in the solve.
`maelys_datalog_decision_t`	Distinguishes allow, reduced access and several deny outcomes.

Used from other pages

These types are defined on the linked pages; this page uses them in the roles below.

Type	Use on this page	Defined in
`maelys_datalog_result_t`	Input result whose filter statistics are read.	Stable Solving

Functions

Function	Purpose
`maelys_datalog_result_filter_statistics()`	Read reference-backend solve statistics.
`maelys_datalog_decision_from_presence()`	Combine three successful membership-query results.

Observe filter work

The statistics are about solving, not the separate Why-false explanation search. They are supported by the canonical reference backend; a custom backend returns UNSUPPORTED, even if it can render text explanations.

typedef struct {
    size_t evaluations;
    size_t matches;
    size_t non_matches;
    size_t cost_units;
} maelys_datalog_filter_statistics_t;

Filter activity accumulated by a reference-backend solve.

Fields

evaluationssize_t

Total filter evaluations.

matchessize_t

Evaluations that matched.

non_matchessize_t

Evaluations that did not match.

cost_unitssize_t

Accumulated filter cost units.

Name	Type	Meaning
evaluations	size_t	Total filter evaluations.
matches	size_t	Evaluations that matched.
non_matches	size_t	Evaluations that did not match.
cost_units	size_t	Accumulated filter cost units.

Decision type

typedef enum {
    MAELYS_DATALOG_DECISION_DENY = 0,
    MAELYS_DATALOG_DECISION_ALLOW = 1,
    MAELYS_DATALOG_DECISION_REDUCED = 2,
    MAELYS_DATALOG_DECISION_DENY_DEFAULT = 3,
    MAELYS_DATALOG_DECISION_DENY_CONFLICT = 4
} maelys_datalog_decision_t;

Explicit outcome after combining allow, reduce and deny presence.

Decision	Meaning
`DENY`	Deny was present alone.
`ALLOW`	Allow was present without reduce or deny.
`REDUCED`	Reduce was present without deny, including alongside allow.
`DENY_DEFAULT`	None of the three routes was present.
`DENY_CONFLICT`	Deny and allow or reduce were both present.

Read filter statistics

maelys_datalog_status_t
maelys_datalog_result_filter_statistics(
const maelys_datalog_result_t *result,
maelys_datalog_filter_statistics_t *out_statistics
);

Reads the reference solver’s filter statistics for this result. These describe solving work, not a later Why-false explanation search.

Arguments

resultconst maelys_datalog_result_t *

Live result from a successful solve.

out_statisticsmaelys_datalog_filter_statistics_t *

Receives the solve counters.

Name	Type	Meaning
result	const maelys_datalog_result_t *	Live result from a successful solve.
out_statistics	maelys_datalog_filter_statistics_t *	Receives the solve counters.

Return value

maelys_datalog_status_t

OK for a live reference-backend result; UNSUPPORTED for another backend.

Compose a final decision

First query allow, reduce and deny successfully; pass each resulting present value as 0 or 1. A failed query is not a 0: handle it as an error and deny before calling this helper. Precedence is deny, then reduce, then allow. If deny and another positive route coexist, the outcome is DENY_CONFLICT; if none is present, it is DENY_DEFAULT.

maelys_datalog_status_t
maelys_datalog_decision_from_presence(
int allow,
int reduce,
int deny,
maelys_datalog_decision_t *out_decision
);

Combines already-known allow, reduce and deny fact presence into an application decision. It does not perform the membership queries itself.

Arguments

allowint

Successful allow query presence, exactly 0 or 1.

reduceint

Successful reduce query presence, exactly 0 or 1.

denyint

Successful deny query presence, exactly 0 or 1.

out_decisionmaelys_datalog_decision_t *

Receives the composed outcome.

Name	Type	Meaning
allow	int	Successful allow query presence, exactly 0 or 1.
reduce	int	Successful reduce query presence, exactly 0 or 1.
deny	int	Successful deny query presence, exactly 0 or 1.
out_decision	maelys_datalog_decision_t *	Receives the composed outcome.

Return value

maelys_datalog_status_t

OK for three valid presence bits; INVALID_ARGUMENT for any other value or a null output.

CODE

static maelys_datalog_status_t combine_checked_presence(
    int allow_present, int reduce_present, int deny_present,
    maelys_datalog_decision_t *out_decision) {
    /* Call only after all three membership queries returned STATUS_OK. */
    return maelys_datalog_decision_from_presence(
        allow_present, reduce_present, deny_present, out_decision);
}

The quickstart's document-access policy derives allow/2 only. It does not define reduce/2 or deny/2, so this is an additional multi-route policy pattern, not a hidden change to that example.