C Advanced API

Structured explanations

Inspect Why-true steps and Why-false obstacles from one prepared explanation lease.

Use text explanations from the Stable Query API when a human-readable document is enough. The Advanced API exposes structured views of the same prepared explanation for applications that need to inspect a derivation step or a failed candidate rule programmatically. It does not run a second explanation search when reading these records.

Types

Defined on this page

Type	Purpose
`maelys_datalog_explanation_info_t`	Kind, completeness and record counts.
`maelys_datalog_explanation_step_view_t`	One Why-true derived fact and its premise range.
`maelys_datalog_explanation_premise_view_t`	Why-true evidence for one rule-body position.
`maelys_datalog_explanation_obstacle_view_t`	Why-false candidate, bindings, support and obstacle.
`maelys_datalog_explanation_support_view_t`	One supporting fact inside a Why-false candidate.

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_prepared_explanation_t`	Input lease whose records are inspected while live.	Stable Querying

Functions

Function	Purpose
`maelys_datalog_prepared_explanation_info()`	Read counts and completeness before indexing.
`maelys_datalog_prepared_explanation_step()`	Read one Why-true step.
`maelys_datalog_prepared_explanation_premise()`	Read one Why-true premise.
`maelys_datalog_prepared_explanation_obstacle()`	Read one Why-false diagnostic candidate.

Prepare once, inspect while the result is live

First call the stable prepare function with caller-owned explanation storage. Then read info, followed by indices below its reported counts. A Why-true step contains a premise_begin and premise_count identifying its entries in the shared premise array. Why-false supplies diagnostic obstacle records instead. IDs and indices are local to this one explanation, not durable policy identifiers.

typedef struct {
    maelys_datalog_explanation_kind_t kind;
    int found, truncated;
    size_t step_count, premise_count;
    unsigned false_status, false_summary, query_origin, limit_hits;
    size_t candidate_rule_count, substitution_count, diagnostic_count, filter_cost_units;
    maelys_datalog_fact_t query;
} maelys_datalog_explanation_info_t;

Metadata for one prepared Why-true or Why-false document.

Fields

kindmaelys_datalog_explanation_kind_t

Requested Why-true or Why-false kind.

foundint

Whether the queried fact is present.

truncatedint

Whether bounded exploration omitted further detail.

step_countsize_t

Why-true record counts.

premise_countsize_t

Why-true record counts.

false_statusunsigned int

Why-false result classification.

false_summaryunsigned int

Why-false result classification.

query_originunsigned int

Origin classification and reached search limits.

limit_hitsunsigned int

Origin classification and reached search limits.

candidate_rule_countsize_t

Why-false exploration counters.

substitution_countsize_t

Why-false exploration counters.

diagnostic_countsize_t

Why-false exploration counters.

filter_cost_unitssize_t

Why-false exploration counters.

querymaelys_datalog_fact_t

Ground fact that was explained.

Name	Type	Meaning
kind	maelys_datalog_explanation_kind_t	Requested Why-true or Why-false kind.
found	int	Whether the queried fact is present.
truncated	int	Whether bounded exploration omitted further detail.
step_count	size_t	Why-true record counts.
premise_count	size_t	Why-true record counts.
false_status	unsigned int	Why-false result classification.
false_summary	unsigned int	Why-false result classification.
query_origin	unsigned int	Origin classification and reached search limits.
limit_hits	unsigned int	Origin classification and reached search limits.
candidate_rule_count	size_t	Why-false exploration counters.
substitution_count	size_t	Why-false exploration counters.
diagnostic_count	size_t	Why-false exploration counters.
filter_cost_units	size_t	Why-false exploration counters.
query	maelys_datalog_fact_t	Ground fact that was explained.

typedef struct {
    size_t rule_id, premise_begin, premise_count;
    maelys_datalog_fact_t fact;
} maelys_datalog_explanation_step_view_t;

One Why-true rule application and its premise span.

Fields

rule_idsize_t

Rule identifier local to this explanation.

premise_beginsize_t

Range in the explanation premise array.

premise_countsize_t

Range in the explanation premise array.

factmaelys_datalog_fact_t

Derived ground fact for this step.

Name	Type	Meaning
rule_id	size_t	Rule identifier local to this explanation.
premise_begin	size_t	Range in the explanation premise array.
premise_count	size_t	Range in the explanation premise array.
fact	maelys_datalog_fact_t	Derived ground fact for this step.

typedef struct {
    unsigned kind, origin, body_index, parent_step;
    maelys_datalog_ir_atom_t atom; /* ground fact, absence, or aggregate source */
    maelys_datalog_ir_comparison_t op;
    maelys_datalog_value_t lhs, rhs, filter_value;
    size_t filter_program_index;
    unsigned filter_kind, projected_variable;
    uint32_t aggregate_value;
} maelys_datalog_explanation_premise_view_t;

One positive fact, absence, comparison, filter or aggregate in a Why-true step.

Fields

kindunsigned int

Premise classification, fact origin, body position and optional parent step.

originunsigned int

Premise classification, fact origin, body position and optional parent step.

body_indexunsigned int

Premise classification, fact origin, body position and optional parent step.

parent_stepunsigned int

Premise classification, fact origin, body position and optional parent step.

atommaelys_datalog_ir_atom_t

Ground atom or comparison according to kind.

opmaelys_datalog_ir_comparison_t

Ground atom or comparison according to kind.

lhsmaelys_datalog_value_t

Values meaningful for comparison, aggregate or filter kinds.

rhsmaelys_datalog_value_t

Values meaningful for comparison, aggregate or filter kinds.

filter_valuemaelys_datalog_value_t

Values meaningful for comparison, aggregate or filter kinds.

filter_program_indexsize_t

Filter identity when this is a filter premise.

filter_kindunsigned int

Filter identity when this is a filter premise.

projected_variableunsigned int

Aggregate projection and value when this is an aggregate premise.

aggregate_valueuint32_t

Aggregate projection and value when this is an aggregate premise.

Name	Type	Meaning
kind	unsigned int	Premise classification, fact origin, body position and optional parent step.
origin	unsigned int	Premise classification, fact origin, body position and optional parent step.
body_index	unsigned int	Premise classification, fact origin, body position and optional parent step.
parent_step	unsigned int	Premise classification, fact origin, body position and optional parent step.
atom	maelys_datalog_ir_atom_t	Ground atom or comparison according to kind.
op	maelys_datalog_ir_comparison_t	Ground atom or comparison according to kind.
lhs	maelys_datalog_value_t	Values meaningful for comparison, aggregate or filter kinds.
rhs	maelys_datalog_value_t	Values meaningful for comparison, aggregate or filter kinds.
filter_value	maelys_datalog_value_t	Values meaningful for comparison, aggregate or filter kinds.
filter_program_index	size_t	Filter identity when this is a filter premise.
filter_kind	unsigned int	Filter identity when this is a filter premise.
projected_variable	unsigned int	Aggregate projection and value when this is an aggregate premise.
aggregate_value	uint32_t	Aggregate projection and value when this is an aggregate premise.

typedef struct {
    unsigned body_index, origin;
    maelys_datalog_fact_t fact;
} maelys_datalog_explanation_support_view_t;

Supporting fact already matched by a Why-false candidate.

Fields

body_indexunsigned int

Body position and fact origin.

originunsigned int

Body position and fact origin.

factmaelys_datalog_fact_t

Matched supporting ground fact.

Name	Type	Meaning
body_index	unsigned int	Body position and fact origin.
origin	unsigned int	Body position and fact origin.
fact	maelys_datalog_fact_t	Matched supporting ground fact.

typedef struct {
    size_t rule_id, depth;
    maelys_datalog_fact_t target;
    uint32_t bound_variable_mask;
    maelys_datalog_value_t substitution[MAELYS_DATALOG_IR_MAX_VARIABLES];
    size_t support_count;
    maelys_datalog_explanation_support_view_t supports[MAELYS_DATALOG_IR_MAX_BODY];
    unsigned obstacle_kind, obstacle_origin, body_index, unbound_term_mask;
    maelys_datalog_ir_atom_t pattern;
    maelys_datalog_ir_comparison_t op;
    maelys_datalog_value_t lhs, rhs, filter_value;
    size_t filter_program_index;
    unsigned filter_kind;
} maelys_datalog_explanation_obstacle_view_t;

One bounded Why-false candidate with bindings, support and the obstacle reached.

Fields

rule_idsize_t

Candidate rule, search depth and target fact.

depthsize_t

Candidate rule, search depth and target fact.

targetmaelys_datalog_fact_t

Candidate rule, search depth and target fact.

bound_variable_maskuint32_t

Bound variables and their candidate values.

substitutionmaelys_datalog_value_t[32]

Bound variables and their candidate values.

support_countsize_t

Positive support found before the obstacle.

supportsmaelys_datalog_explanation_support_view_t[8]

Positive support found before the obstacle.

obstacle_kindunsigned int

Obstacle classification and body position.

obstacle_originunsigned int

Obstacle classification and body position.

body_indexunsigned int

Obstacle classification and body position.

unbound_term_maskunsigned int

Obstacle classification and body position.

patternmaelys_datalog_ir_atom_t