@spec add_fact(t(), relation_name(), fact_values()) :: t() | {:error, String.t()}

Adds a ground fact to the program.

The relation must be declared via add_relation/3 and the number of values must match the relation's arity.

Returns {:error, reason} if:

• The relation is not defined.
• The arity of values does not match the relation schema.
• A value in values is not an integer, string, or atom (floats are not supported).

Examples

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

iex> alias ExDatalog.Program
iex> program = Program.new() |> Program.add_relation("parent", [:atom, :atom])
iex> {:error, _} = Program.add_fact(program, "unknown", [:alice])
{:error, "relation \"unknown\" is not defined"}

@spec add_relation(t(), relation_name(), [ir_type()]) :: t() | {:error, String.t()}

Adds a relation schema to the program.

types is a list of type atoms (:integer, :string, :atom, :any) with length equal to the arity of the relation.

Returns {:error, reason} if:

• name is empty.
• types is empty.
• The relation already exists.

Examples

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

iex> {:error, _} = ExDatalog.Program.add_relation(ExDatalog.Program.new(), "", [:atom])
{:error, "relation name must be a non-empty string"}

@spec add_rule(t(), ExDatalog.Rule.t()) :: t() | {:error, String.t()}

Adds a rule to the program.

Performs structural validation:

• The head relation must be declared.
• The head arity must match the relation schema.
• All body atoms must reference declared relations with matching arities.

Semantic validation (variable safety, stratification) is deferred to ExDatalog.Validator.

Returns {:error, reason} if any structural check fails.

Examples

iex> alias ExDatalog.{Program, Rule, Atom, Term}
iex> program =
...>   Program.new()
...>   |> Program.add_relation("parent", [:atom, :atom])
...>   |> Program.add_relation("ancestor", [:atom, :atom])
iex> rule = Rule.new(
...>   Atom.new("ancestor", [Term.var("X"), Term.var("Y")]),
...>   [{:positive, Atom.new("parent", [Term.var("X"), Term.var("Y")])}]
...> )
iex> result = Program.add_rule(program, rule)
iex> length(result.rules) == 1
true

@spec add_rule(t(), head_shorthand(), [body_literal_shorthand()], [
  constraint_shorthand()
]) ::
  t() | {:error, String.t()}

Adds a rule using shorthand notation for the head atom, body literals, and constraints.

This is a more ergonomic alternative to add_rule/2 that avoids the need for explicit Rule.new/3, ExDatalog.Atom.new/2, and ExDatalog.Term.var/1 calls.

The head is a tuple {"relation", [terms...]} where each term follows the Prolog-inspired convention:

• Uppercase atoms become logic variables (:X → {:var, "X"})
• :_ becomes a wildcard
• Lowercase atoms and other values become constants

Each body literal is {:positive, {"rel", [terms...]}} or {:negative, {"rel", [terms...]}}. You may also mix in structs like {:positive, ExDatalog.Atom.new(...)}.

Each constraint is an operator tuple like {:neq, :A, :B} or {:add, :X, :Y, :Z}. You may also use existing %Constraint{} structs.

Returns {:error, reason} if any structural check fails (same validation as add_rule/2).

Examples

iex> alias ExDatalog.Program
iex> program =
...>   Program.new()
...>   |> Program.add_relation("parent", [:atom, :atom])
...>   |> Program.add_relation("ancestor", [:atom, :atom])
iex> result = Program.add_rule(program,
...>   {"ancestor", [:X, :Y]},
...>   [{:positive, {"parent", [:X, :Y]}}]
...> )
iex> length(result.rules) == 1
true

iex> alias ExDatalog.Program
iex> program =
...>   Program.new()
...>   |> Program.add_relation("income", [:atom, :integer])
...>   |> Program.add_relation("high_earner", [:atom])
iex> result = Program.add_rule(program,
...>   {"high_earner", [:X]},
...>   [{:positive, {"income", [:X, :S]}}],
...>   [{:gt, :S, 100_000}]
...> )
iex> length(result.rules) == 1
true

@spec has_relation?(t(), relation_name()) :: boolean()

Returns true if the relation is defined in the program.

Examples

iex> alias ExDatalog.Program
iex> program = Program.new() |> Program.add_relation("parent", [:atom, :atom])
iex> Program.has_relation?(program, "parent")
true

iex> alias ExDatalog.Program
iex> Program.has_relation?(Program.new(), "unknown")
false

@spec new() :: t()

Creates a new, empty Datalog program.

Examples

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

@spec relation(t(), relation_name()) :: relation_schema() | nil

Returns the schema for a relation, or nil if not defined.

Examples

iex> alias ExDatalog.Program
iex> program = Program.new() |> Program.add_relation("parent", [:atom, :atom])
iex> Program.relation(program, "parent")
%{arity: 2, types: [:atom, :atom]}

iex> alias ExDatalog.Program
iex> Program.relation(Program.new(), "unknown")
nil