@spec facts(t()) :: [term()]

Every fact the session holds, inserted or concluded.

Unordered. A session is a set of facts, not a sequence.

The two halves answer on different clocks. insert/2 and retract/2 update working memory at once, so an inserted fact appears here before anything matches it. A concluded fact is as of the most recent fire, because concluding one is what fire_rules/2 does. So a session with a queued retract shows the conclusions that rested on the fact it took out. settled?/1 reports whether a fire is owed.

@spec fire_rules(
  t(),
  keyword()
) :: t()

Fires rules until the agenda is empty, returning a new session.

Options:

• :max_cycles — how many cycles one call may fire. A cycle is one pass of the fire loop: one activation at the default concurrency, one whole activation group above it. :infinity by default: the engine runs to quiescence, and an oscillating ruleset spins rather than raising. Give it an integer to bound the call. A ruleset that exceeds it raises with the rules that fired most. One that fires the whole allowance and then settles is fine. See docs/design/observability.md §3 for how to pick a number.
• :concurrency — how many rule bodies of one activation group run at once. 1 by default, which fires them one at a time. Raise it when a body does I/O or real computation. The bodies of a group then run on tasks, and their conclusions are applied in group order. A body that only builds a tuple is about 1.5% of firing, and it costs more than that to hand to a task, so the default suits ordinary rules. Above 1, a body runs on a task. It does not inherit Logger.metadata, and its bindings are copied, which is expensive for a collection binding.
• :timeout — milliseconds one body may take, or :infinity, the default. Applies only when :concurrency is above 1.

This is the only call that propagates. insert/2 and retract/2 queue work. Firing drains that queue, matches everything waiting, runs the rules that match, and returns at quiescence. So a session you have not fired holds facts but no matches.

iex> alias Rete.Session
iex> queued =
...>   Session.new([Rete.Doc.Orders])
...>   |> Session.insert([{:customer, 1}, {:order, 1, 250}])
iex> Rete.Doc.Orders.flagged_for(queued)
[]
iex> Rete.Doc.Orders.flagged_for(Session.fire_rules(queued))
[{1, 250}]

@spec from_network(Rete.Network.t()) :: t()

Builds an empty session over an already compiled network.

The network is immutable, so one can back any number of independent sessions.

@spec insert(t(), term() | [term()]) :: t()

Inserts one fact or a list of them, returning a new session.

Facts are a multiset. Inserting a fact equal to one already present bumps its count instead of duplicating its matches, so retracting one occurrence leaves the other.

Inserting does not match anything. It records the fact and queues the work. fire_rules/2 is what matches, and until you call it no rule has seen the fact.

iex> alias Rete.Session
iex> session = Session.new([Rete.Doc.Orders]) |> Session.insert({:customer, 1})
iex> Session.facts(session)
[{:customer, 1}]

@spec listener_state(t(), module()) :: term()

What a listener has accumulated, or nil if it is not attached.

@spec network(t()) :: Rete.Network.t()

The compiled network behind a session.

@spec new(
  [module()],
  keyword()
) :: t()

Builds a session from ruleset modules.

Options go to Rete.Compiler.build/2. Compiling the network is the expensive part, so a long-lived application should do it once and use from_network/1.

iex> Rete.Session.new([Rete.Doc.Orders]) |> Rete.Session.facts()
[]

@spec query(t(), {module(), atom()}, keyword() | %{required(atom()) => term()}) :: [
  term()
]

Runs a query by {module, name}: one result per match, computed by its body.

Usually you would not write this. defquery flagged_for(...) defines flagged_for/2 in its own module, so the same call reads Rete.Doc.Orders.flagged_for(session, cid: 1), which the compiler checks. Use this form when the query is decided at runtime.

A query is addressed by module and name together because two rulesets composed into one session may each define a :summary.

filters narrows the matches by equality on the bindings, before the body runs. It may name any variable the left hand side binds, as a keyword list or a map. There is no separate parameter declaration. Naming something the query does not bind raises an error, instead of answering [].

A query answers as of the most recent fire. On a session you never fired that is []. On one you fired and then inserted into, it is the answer from before that insert, which is stale rather than empty. A query reads propagated state either way, and it does not raise. Rete.Inspect.why_not/2 raises in the same position, because a diagnostic that reports "nothing matched" is misleading when the truth is "nothing has been matched yet". A result set is not. Call settled?/1 to tell the two cases apart.

Row order is unspecified. Rows come back in the order the facts arrived, so the same facts fed in a different order answer in a different order. Sort the result yourself if order matters to you.

The set of rows never varies, and one feed always answers the same way.

A query looks at every match it holds unless Rete.Ruleset.index/2 declared an index the filter covers. An index changes speed and nothing else: the rows and their order are the same either way. Rete.Inspect.query_plan/3 reports which index a filter would use.

iex> alias Rete.Session
iex> session =
...>   Session.new([Rete.Doc.Orders])
...>   |> Session.insert([{:customer, 1}, {:order, 1, 250}])
...>   |> Session.fire_rules()
iex> Session.query(session, {Rete.Doc.Orders, :flagged_for}, cid: 1)
[{1, 250}]

A second order, queued and not yet fired. The answer is the one from before it, not []:

iex> alias Rete.Session
iex> stale =
...>   Session.new([Rete.Doc.Orders])
...>   |> Session.insert([{:customer, 1}, {:order, 1, 250}])
...>   |> Session.fire_rules()
...>   |> Session.insert({:order, 1, 900})
iex> Session.settled?(stale)
false
iex> Session.query(stale, {Rete.Doc.Orders, :flagged_for}, cid: 1)
[{1, 250}]
iex> fired = Session.fire_rules(stale)
iex> fired |> Session.query({Rete.Doc.Orders, :flagged_for}, cid: 1) |> Enum.sort()
[{1, 250}, {1, 900}]

@spec retract(t(), term() | [term()]) :: t()

Retracts one fact or a list of them, returning a new session.

Anything concluded from them is retracted too, transitively. Retracting a fact that is not present does nothing.

Like insert/2, this queues the work rather than doing it. The fact leaves at once, and the conclusions that rested on it leave when fire_rules/2 drains the queue.

iex> alias Rete.Session
iex> session =
...>   Session.new([Rete.Doc.Orders])
...>   |> Session.insert([{:customer, 1}, {:order, 1, 250}])
...>   |> Session.fire_rules()
...>   |> Session.retract({:customer, 1})
...>   |> Session.fire_rules()
iex> Session.facts(session)
[{:order, 1, 250}]

@spec settled?(t()) :: boolean()

Whether the session has no work waiting for fire_rules/2.

false means insert/2 or retract/2 recorded a fact that no rule has seen yet. A query on such a session answers as though the fact never arrived, so this is the check to make when you did not write the insert/2 yourself.

A session fresh from new/1 is not settled. new/1 queues the root token, which the first fire plants. So a rule with no conditions has not fired yet either.

iex> alias Rete.Session
iex> queued = Session.new([Rete.Doc.Orders]) |> Session.insert({:customer, 1})
iex> Session.settled?(queued)
false
iex> Session.settled?(Session.fire_rules(queued))
true

@spec with_listener(t(), module(), term()) :: t()

Attaches a listener, returning a new session.

The listener sees every event from now on. Read what it accumulated with listener_state/2. Attaching several is fine, and they see events in attachment order.

iex> alias Rete.Session
iex> Session.new([Rete.Doc.Orders])
...> |> Session.with_listener(Rete.Listener.Collect, [])
...> |> Session.insert({:customer, 1})
...> |> Rete.Listener.Collect.by_tag(:fact_inserted)
[{:fact_inserted, {:customer, 1}, :asserted}]