@spec compile(ExDatalog.Program.t()) ::
  {:ok, ExDatalog.IR.t()} | {:error, [ExDatalog.Validator.Error.t()]}

Compiles a validated program to an engine-neutral IR.

Runs validation first. Returns {:ok, %ExDatalog.IR{}} or {:error, errors}.

The IR is deterministic: the same program always produces the same IR. Rules are sorted by (stratum, relation_name, rule_id). Facts are sorted by (relation_name, values). Relations are sorted by name.

Examples

 iex> alias ExDatalog.{Program, Rule, Atom, Term}
 iex> program =
 ...>   Program.new()
 ...>   |> Program.add_relation("edge", [:atom, :atom])
 ...>   |> Program.add_relation("path", [:atom, :atom])
 ...>   |> Program.add_rule(
 ...>     Rule.new(
 ...>       Atom.new("path", [Term.var("X"), Term.var("Y")]),
 ...>       [{:positive, Atom.new("edge", [Term.var("X"), Term.var("Y")])}]
 ...>     )
 ...>   )
 iex> {:ok, ir} = ExDatalog.compile(program)
 iex> length(ir.rules) == 1 and length(ir.relations) == 2
 true
 true

@spec evaluate(
  ExDatalog.IR.t(),
  keyword()
) :: {:ok, ExDatalog.Knowledge.t()} | {:error, term()}

Evaluates a compiled IR program against a backend engine.

Returns {:ok, ExDatalog.Knowledge.t()} or {:error, reason}.

Options

• :engine — backend module (default: ExDatalog.Engine.Naive)
• :storage — storage module (default: ExDatalog.Storage.Map)
• :max_iterations — fixpoint iteration limit (default: 10_000)
• :timeout_ms — wall-clock timeout in ms (default: 30_000)

Check knowledge.stats.termination for :fixpoint, :iteration_limit, or :timeout to determine whether evaluation completed.

@spec materialize(
  ExDatalog.Program.t(),
  keyword()
) ::
  {:ok, ExDatalog.Knowledge.t()}
  | {:error, [ExDatalog.Validator.Error.t()] | term()}

One-shot: validate, compile, and materialize a program.

Equivalent to validate/1 → compile/1 → evaluate/2.

Returns {:ok, ExDatalog.Knowledge.t()} or {:error, reason}.

Aggregate input types

Aggregates (sum, min, max) are integer-only. If an aggregate's input resolves to a non-integer value at reduction time, evaluation raises ArgumentError rather than returning {:error, reason}. A non-integer aggregate input is treated as a data-modeling error and surfaces loudly. If the input domain is untrusted, constrain it with a type predicate (for example is_integer/1) earlier in the rule body, or wrap the call in a try.

Options

See evaluate/2 for available options, plus:

• :goal — {relation, pattern} used both as the magic-sets goal (when strategy: :magic_sets) and as a post-materialization filter (default: nil). When set, the knowledge base's relations map contains only the matching tuples for the specified relation. The pattern uses :_ as a wildcard, matching Knowledge.match/3.

Examples

 iex> alias ExDatalog.{Program, Rule, Atom, Term}
 iex> program =
 ...>   Program.new()
 ...>   |> Program.add_relation("parent", [:atom, :atom])
 ...>   |> Program.add_fact("parent", [:alice, :bob])
 iex> {:ok, knowledge} = ExDatalog.materialize(program)
 iex> ExDatalog.Knowledge.size(knowledge, "parent")
 1

@spec new() :: ExDatalog.Program.t()

Creates a new, empty Datalog program.

Delegates to ExDatalog.Program.new/0.

Examples

 iex> ExDatalog.new()
 %ExDatalog.Program{relations: %{}, facts: [], rules: []}

 iex> alias ExDatalog.Program
 iex> ExDatalog.new() |> Program.add_relation("edge", [:atom, :atom])
 %ExDatalog.Program{relations: %{"edge" => %{arity: 2, types: [:atom, :atom]}}, facts: [], rules: []}

@spec validate(ExDatalog.Program.t()) ::
  {:ok, ExDatalog.Program.t()} | {:error, [ExDatalog.Validator.Error.t()]}

Validates a program, returning structural and semantic errors.

Returns {:ok, program} if valid, {:error, errors} otherwise. errors is a list of ExDatalog.Validator.Error.t().

Structural checks (Phase 1):

• Relation references exist.
• Arities match declared schemas.
• Terms are valid.

Semantic checks (Phase 2):

• Variable safety and range restriction.
• Constraint binding and ordering.
• Stratified negation.

Examples

 iex> alias ExDatalog.Program
 iex> program = Program.new() |> Program.add_relation("edge", [:atom, :atom])
 iex> {:ok, validated} = ExDatalog.validate(program)
 iex> is_struct(validated, ExDatalog.Program)
 true