relationalai 0.13.5__py3-none-any.whl → 1.0.0a2__py3-none-any.whl

v0/relationalai/semantics/lqp/rewrite/functional_dependencies.py

@@ -0,0 +1,314 @@
+from __future__ import annotations
+from typing import Optional, Sequence
+from v0.relationalai.semantics.internal import internal
+from v0.relationalai.semantics.metamodel.ir import (
+    Node, Require, Logical, Var, Relation, Lookup, ScalarType
+)
+from v0.relationalai.semantics.metamodel import builtins
+
+
+"""
+Helper functions for converting `Require` nodes with unique constraints to functional
+dependencies. The main functionalities provided are:
+    1. Check whether a `Require` node is a valid unique constraint representation
+    2. Represent the uniqueness constraint as a functional dependency
+    3. Check if the functional dependency is structural i.e., can be represented with
+         `@function(k)` annotation on a single relation.
+
+=========================== Structure of unique constraints ================================
+A `Require` node represents a _unique constraint_ if it meets the following criteria:
+ * the `Require` node's `domain` is an empty `Logical` node
+ * the `Require` node's `checks` has a single `Check` node
+ * the single `Check` node has `Logical` task that is a list of `Lookup` tasks
+ * precisely one `Lookup` task in the `Check` uses the `unique` builtin relation name
+ * the `unique` lookup has precisely one argument, which is a `TupleArg` or a `tuple`
+   containing at least one `Var`
+ * all `Lookup` nodes use variables only (no constants)
+ * the variables used in the `unique` lookup are a subset of the variables used in other
+   lookups
+============================================================================================
+
+We use the following unique constraint as the running example.
+
+```
+Require
+  domain
+    Logical
+  checks:
+    Check
+      check:
+        Logical
+          Person(person::Person)
+          first_name(person::Person, firstname::String)
+          last_name(person::Person, lastname::String)
+          unique((firstname::String, lastname::String))
+      error:
+        ...
+```
+
+=========================== Semantics of unique constraints ================================
+A unique constraint states that the columns declared in the `unique` predicate must be
+unique in the result of the conjunctive query consisting of all remaining predicates.
+============================================================================================
+
+In the running example, the conjunctive query computes a table with 3 columns, the person id
+`person::Person`, the first name `firstname::String`, and the last name `lastname::String`.
+The uniqueness predicate `unique((firstname::String, lastname::String))` states that no person
+can have more than a single combination of first and last name.
+
+The unique constraint in the running example above corresponds to the following functional
+dependency.
+
+```
+Person(x) ∧ first_name(x, y) ∧ last_name(x, z): {y, z} -> {x}
+```
+
+------------------------------ Redundant Type Atoms ----------------------------------------
+At the time of writing, PyRel does not yet remove redundant unary atoms. For instance, in
+the running example, the atom `Person(person::Person)` is redundant because the type of the
+`person` variable is specified in the other two atoms `first_name` and `last_name`.
+Consequently, we identify redundant atoms and remove them from the definition of the
+corresponding functional dependency.
+
+Formally, a _guard_ atom is any `Lookup` node whose relation name is not `unique`. Now, a
+unary guard atom `T(x::T)` is _redundant_ if the uniqueness constraint has a non-unary guard
+atom `R(...,x::T,...)`.
+
+================================ Normalized FDs ============================================
+Now, the _(normalized)_ functional dependency_ corresponding to a unique constraint is an
+object of the form `φ: X → Y`, where :
+ 1. `φ` is the set of all non-redundant guard atoms.
+ 2. `X` is the set of variables used in the `unique` atom
+ 3. `Y` is the set of all other variables used in the constraint
+============================================================================================
+
+The normalized functional dependency corresponding to the unique constraints from the running
+example is :
+```
+first_name(person::Person, firstname::String) ∧ last_name(person::Person, lastname::String): {firstname:String, lastname:String} -> {person:Person}
+```
+Note that the unary atom `Person(person::Person)` is redundant and thus omitted from the
+decomposition.
+
+Some simple functional dependencies can, however, be expressed simply with `@function(k)`
+attribute of a single relation.  Specifically, a functional dependency `φ: X → Y` is
+_structural_ if φ consists of a single atom `R(x1,...,xm,y1,...,yk)` and `X = {x1,...,xm}`.
+"""
+
+#
+# Checks that an input `Require` node is a valid unique constraint. Returns `None` if not.
+# If yes, we return the decomposition of the unique constraint as a tuple
+# `(all_vars, unique_vars, guard)`, where
+# - `all_vars` is the list of all variables used in the constraint
+# - `unique_vars` is the list of variables used in the `unique` atom
+# - `guard` is the list of all other `Lookup` atoms
+#
+def _split_unique_require_node(node: Require) -> Optional[tuple[list[Var], list[Var], list[Lookup]]]:
+    if not isinstance(node.domain, Logical):
+        return None
+    if len(node.domain.body) != 0:
+        return None
+    if len(node.checks) != 1:
+        return None
+    check = node.checks[0]
+    if not isinstance(check.check, Logical):
+        return None
+
+    unique_atom: Optional[Lookup] = None
+    guard: list[Lookup] = []
+    for task in check.check.body:
+        if not isinstance(task, Lookup):
+            return None
+        if task.relation.name == builtins.unique.name:
+            if unique_atom is not None:
+                return None
+            unique_atom = task
+        else:
+            guard.append(task)
+
+    if unique_atom is None:
+        return None
+
+    # collect variables
+    all_vars: list[Var] = []
+    for lookup in guard:
+        for arg in lookup.args:
+            if not isinstance(arg, Var):
+                return None
+            if arg in all_vars:
+                continue
+            all_vars.append(arg)
+
+    unique_vars: list[Var] = []
+    if len(unique_atom.args) != 1:
+        return None
+    if not isinstance(unique_atom.args[0], (internal.TupleArg, tuple)):
+        return None
+    if len(unique_atom.args[0]) == 0:
+        return None
+    for arg in unique_atom.args[0]:
+        if not isinstance(arg, Var):
+            return None
+        if arg in unique_vars:
+            return None
+        unique_vars.append(arg)
+
+    # check that unique vars are a subset of other vars
+    if not set(unique_vars).issubset(set(all_vars)):
+        return None
+
+    return list(all_vars), list(unique_vars), guard
+
+
+def is_valid_unique_constraint(node: Require) -> bool:
+    """
+    Checks whether the input `Require` node is a valid unique constraint. See description at
+    the top of the file for details.
+    """
+    return _split_unique_require_node(node) is not None
+
+#
+# A unary guard atom `T(x::T)` is redundant if the constraint contains a non-unary atom
+# `R(...,x::T,...)`.  We discard all redundant guard atoms in the constructed fd.
+#
+def normalized_fd(node: Require) -> Optional[FunctionalDependency]:
+    """
+    If the input `Require` node is a uniqueness constraint, constructs its reduced
+    functional dependency `φ: X -> Y`, where `φ` contains all non-redundant guard atoms,
+    `X` are the variables used in the `unique` atom, and `Y` are the remaining variables.
+    Returns `None` if the input node is not a valid uniqueness constraint.
+    """
+    parts = _split_unique_require_node(node)
+    if parts is None:
+        return None
+    all_vars, unique_vars, guard_atoms = parts
+
+    # remove redundant lookups
+    redundant_guard_atoms: list[Lookup] = []
+    for atom in guard_atoms:
+        # the atom is unary A(x::T)
+        if len(atom.args) != 1:
+            continue
+        var = atom.args[0]
+        assert isinstance(var, Var)
+        # T is a scalar type (which includes entity types)
+        var_type = var.type
+        if not isinstance(var_type, ScalarType):
+            continue
+        # the atom is a entity typing T(x::T) i.e., T = A (and hence not a Boolean property)
+        var_type_name = var_type.name
+        rel_name = atom.relation.name
+        if rel_name != var_type_name:
+            continue
+        # Found an atom of the form T(x::T)
+        # check if there is another atom R(...,x::T,...)
+        for typed_atom in guard_atoms:
+            if len(typed_atom.args) == 1:
+                continue
+            if var in typed_atom.args:
+                redundant_guard_atoms.append(atom)
+                break
+
+    guard = [atom for atom in guard_atoms if atom not in redundant_guard_atoms]
+    keys = unique_vars
+    values = [v for v in all_vars if v not in keys]
+
+    return FunctionalDependency(guard, keys, values)
+
+class FunctionalDependency:
+    """
+    Represents a functional dependency of the form `φ: X -> Y`, where
+     - `φ` is a set of `Lookup` atoms
+     - `X` and `Y` are disjoint and covering sets of variables used in `φ`
+    """
+    def __init__(self, guard: Sequence[Lookup], keys: Sequence[Var], values: Sequence[Var]):
+        self.guard = tuple(guard)
+        self.keys = tuple(keys)
+        self.values = tuple(values)
+        assert set(self.keys).isdisjoint(set(self.values)), "Keys and values must be disjoint"
+
+        # for structural fd check
+        self._is_structural:bool = False
+        self._structural_relation:Optional[Relation] = None
+        self._structural_rank:Optional[int] = None
+
+        self._determine_is_structural()
+
+    # A functional dependency `φ: X → Y` is _k-functional_ if `φ` consists of a single atom
+    # `R(x1,...,xm,y1,...,yk)` and `X = {x1,...,xm}`. Not all functional dependencies are
+    # k-functional. For instance, `R(x, y, z): {y, z} → {x}` cannot be expressed with
+    # `@function`. neither can `R(x, y) ∧ P(x, z) : {x} → {y, z}`.
+    def _determine_is_structural(self):
+        if len(self.guard) != 1:
+            self._is_structural = False
+            return
+        atom = next(iter(self.guard))
+        atom_vars = atom.args
+        if len(atom_vars) <= len(self.keys): # @function(0) provides no information
+            self._is_structural = False
+            return
+        prefix_vars = atom_vars[:len(self.keys)]
+        if set(prefix_vars) != set(self.keys):
+            self._is_structural = False
+            return
+        self._is_structural = True
+        self._structural_relation = atom.relation
+        self._structural_rank = len(atom_vars) - len(self.keys)
+
+    @property
+    def is_structural(self) -> bool:
+        """
+        Whether the functional dependency is functional, i.e., can be represented
+        with `@function(k)` annotation on a single relation.
+        """
+        return self._is_structural
+
+    @property
+    def structural_relation(self) -> Relation:
+        """
+        The structural relation of a functional dependency. Raises ValueError if the functional
+        dependency is not structural.
+        """
+        if not self._is_structural:
+            raise ValueError("Functional dependency is not structural")
+        assert self._structural_relation is not None
+        return self._structural_relation
+
+    @property
+    def structural_rank(self) -> int:
+        """
+        The structural rank k of k-structural fd. Raises ValueError if the structural
+        dependency is not k-structural.
+        """
+        if not self._is_structural:
+            raise ValueError("Functional dependency is not structural")
+        assert self._structural_rank is not None
+        return self._structural_rank
+
+    def __str__(self) -> str:
+        guard_str = " ∧ ".join([str(atom) for atom in self.guard]).strip()
+        keys_str = ", ".join([str(var) for var in self.keys]).strip()
+        values_str = ", ".join([str(var) for var in self.values]).strip()
+        return f"{guard_str}: {{{keys_str}}} -> {{{values_str}}}"
+
+def contains_only_declarable_constraints(node: Node) -> bool:
+    """
+    Checks whether the input `Logical` node contains only `Require` nodes annotated with
+    `declare_constraint`.
+    """
+    if not isinstance(node, Logical):
+        return False
+    if len(node.body) == 0:
+        return False
+    for task in node.body:
+        if not isinstance(task, Require):
+            return False
+        if not is_declarable_constraint(task):
+            return False
+    return True
+
+def is_declarable_constraint(node: Require) -> bool:
+    """
+    Checks whether the input `Require` node is annotated with `declare_constraint`.
+    """
+    return builtins.declare_constraint_annotation in node.annotations

v0/relationalai/semantics/lqp/rewrite/quantify_vars.py

@@ -0,0 +1,296 @@
+from __future__ import annotations
+
+from v0.relationalai.semantics.metamodel import ir, factory as f, helpers
+from v0.relationalai.semantics.metamodel.compiler import Pass
+from v0.relationalai.semantics.metamodel.visitor import Visitor, Rewriter
+from v0.relationalai.semantics.metamodel.util import OrderedSet, ordered_set
+from typing import Optional, Any, Tuple, Iterable
+from .functional_dependencies import contains_only_declarable_constraints
+
+class QuantifyVars(Pass):
+    """
+    Introduce existential quantifiers as closely as possible to the affected sub-tasks.
+    """
+
+    def rewrite(self, model: ir.Model, options:dict={}) -> ir.Model:
+        var_info = VarScopeInfo()
+        model.root.accept(var_info)
+        quant_nodes = FindQuantificationNodes(var_info)
+        model.root.accept(quant_nodes)
+        return QuantifyVarsRewriter(quant_nodes).walk(model)
+
+def _ignored_vars(node: ir.Logical|ir.Not):
+    if isinstance(node, ir.Not):
+        return ordered_set()
+
+    vars_to_ignore = ordered_set()
+    for task in node.body:
+        if isinstance(task, ir.Output):
+            # Vars that are output don't need to be quantified.
+            vars_to_ignore.update(helpers.output_vars(task.aliases))
+
+        elif isinstance(task, ir.Update):
+            # Vars that are in effects don't need to be quantified.
+            vars_to_ignore.update(helpers.vars(task.args))
+
+        elif isinstance(task, ir.Aggregate):
+            # Variables that are inputs to an aggregate don't need to be quantified.
+            for var in helpers.vars(task.args):
+                if helpers.is_aggregate_input(var, task):
+                    vars_to_ignore.add(var)
+            # Variables that are in the projections, and not in the group-by, don't need to be quantified.
+            for var in task.projection:
+                if var not in task.group:
+                    vars_to_ignore.add(var)
+
+        elif isinstance(task, ir.Rank):
+            # Variables that are keys, and not in the group-by, don't need to be quantified.
+            for var in task.args + task.projection:
+                if var not in task.group:
+                    vars_to_ignore.add(var)
+
+    return vars_to_ignore
+
+class VarScopeInfo(Visitor):
+    """
+    Compute which variables are still in scope for a given node.
+    Those variables will be potentially quantified in this node.
+    """
+
+    # Keep track of variables that are still in scope for a given node.
+    # Variables are introduced into scope in Var nodes and then propagated upwards.
+    # The propagation stops when:
+    # 1. They are explicitly quantified, or
+    # 2. A node that needs to quantify them is identified.
+    #    That node will be the top-most node that still has them in scope.
+    _vars_in_scope: dict[int, OrderedSet[ir.Var]]
+
+    IGNORED_NODES = (ir.Type,
+                    ir.Var, ir.Literal, ir.Relation, ir.Field,
+                    ir.Default, ir.Output, ir.Update, ir.Aggregate,
+                    ir.Check, ir.Require,
+                    ir.Annotation, ir.Rank)
+
+    def __init__(self):
+        super().__init__()
+        self._vars_in_scope = {}
+
+    def leave(self, node: ir.Node, parent: Optional[ir.Node]=None):
+        if contains_only_declarable_constraints(node):
+            return node
+
+        if isinstance(node, ir.Lookup):
+            self._record(node, helpers.vars(node.args))
+
+        elif isinstance(node, ir.Data):
+            self._record(node, helpers.vars(node.vars))
+
+        elif isinstance(node, ir.Construct):
+            self._record(node, helpers.vars(node.values))
+            self._record(node, [node.id_var])
+
+        elif isinstance(node, ir.Exists) or isinstance(node, ir.ForAll):
+            # Exists and ForAll inherit the vars in scope from their sub-task,
+            # but then remove the vars they quantify over.
+            scope_vars = self._vars_in_scope.get(node.task.id, None)
+            if scope_vars:
+                scope_vars.difference_update(node.vars)
+                self._record(node, scope_vars)
+
+        elif isinstance(node, ir.Not):
+            # Not inherits the vars in scope from its sub-task.
+            scope_vars = self._vars_in_scope.get(node.task.id, None)
+            self._record(node, scope_vars)
+
+        elif isinstance(node, (ir.Match, ir.Union)):
+            # Match/Union inherits the vars in scope from its sub-tasks.
+            scope_vars = ordered_set()
+            for task in node.tasks:
+                sub_scope_vars = self._vars_in_scope.get(task.id, None)
+                if sub_scope_vars:
+                    scope_vars.update(sub_scope_vars)
+            # Hoisted vars are not considered for quantification at this level.
+            scope_vars.difference_update(helpers.hoisted_vars(node.hoisted))
+            self._record(node, scope_vars)
+
+        elif isinstance(node, ir.Logical):
+            self._do_logical(node)
+
+        else:
+            assert isinstance(node, self.IGNORED_NODES), f"Unexpected node kind ({node.kind}) -> {node}"
+
+        return node
+
+    def _do_logical(self, node: ir.Logical):
+        ignored_vars = _ignored_vars(node)
+
+        scope_vars = ordered_set()
+        all_nested_vars = ordered_set()
+        output_vars = ordered_set()
+
+        # Collect all variables from logical sub-tasks
+        for task in node.body:
+            if isinstance(task, ir.Output):
+                output_vars.update(helpers.output_vars(task.aliases))
+
+            if isinstance(task, (ir.Aggregate, ir.Rank)):
+                # Variables that are in the group-by, and not in the projections, can come into scope.
+                for var in task.group:
+                    if var not in task.args:
+                        scope_vars.add(var)
+                continue
+
+            sub_scope_vars = self._vars_in_scope.get(task.id, None)
+
+            # Hoisted variables from sub-tasks are brought again into scope.
+            if isinstance(task, (ir.Logical, ir.Union, ir.Match)):
+                scope_vars.update(helpers.hoisted_vars(task.hoisted))
+
+            if sub_scope_vars:
+                if isinstance(task, ir.Logical):
+                    all_nested_vars.update(sub_scope_vars)
+                elif not isinstance(task, ir.Not):
+                    # For all other node kinds (except Not), just propagate the variables in scope.
+                    # Not nodes stop the propagation of variables coming from their sub-tasks.
+                    scope_vars.update(sub_scope_vars)
+
+        # Nested variables also need to be introduced, provided they are not output variables.
+        for var in all_nested_vars:
+            if var not in output_vars:
+                scope_vars.add(var)
+
+        if scope_vars:
+            scope_vars.difference_update(ignored_vars)
+            # Hoisted vars are not considered for quantification at this level.
+            scope_vars.difference_update(helpers.hoisted_vars(node.hoisted))
+            self._record(node, scope_vars)
+
+    def _record(self, node: ir.Node, vars: Iterable[ir.Var]|None):
+        if not vars:
+            return
+        if node.id not in self._vars_in_scope:
+            self._vars_in_scope[node.id] = ordered_set()
+        self._vars_in_scope[node.id].update(vars)
+
+class FindQuantificationNodes(Visitor):
+    """
+    Find the top-most nodes that need to quantify a variable.
+    The same variable may be quantified at different points assuming they are not parent/child.
+    E.g.,
+    Logical
+        Exists(x)
+            ...
+    Logical
+        Exists(x, y)
+            ...
+    """
+
+    node_quantifies_vars: dict[int, OrderedSet[ir.Var]]
+
+    def __init__(self, var_info: VarScopeInfo):
+        super().__init__()
+        self._vars_in_scope = var_info._vars_in_scope
+        self._handled_vars = ordered_set()
+        self.node_quantifies_vars = {}
+
+    def enter(self, node: ir.Node, parent: Optional[ir.Node]=None) -> "Visitor":
+        if contains_only_declarable_constraints(node):
+            return self
+
+        if isinstance(node, (ir.Logical, ir.Not)):
+            ignored_vars = _ignored_vars(node)
+            self._handled_vars.update(ignored_vars)
+
+            scope_vars = self._vars_in_scope.get(node.id, None)
+            if scope_vars:
+                scope_vars.difference_update(self._handled_vars)
+                if scope_vars:
+                    self._handled_vars.update(scope_vars)
+                    self.node_quantifies_vars[node.id] = scope_vars
+        return self
+
+    def leave(self, node: ir.Node, parent: Optional[ir.Node]=None) -> ir.Node:
+        if contains_only_declarable_constraints(node):
+            return node
+
+        if isinstance(node, (ir.Logical, ir.Not)):
+            ignored_vars = _ignored_vars(node)
+            self._handled_vars.difference_update(ignored_vars)
+
+            scope_vars = self._vars_in_scope.get(node.id, None)
+            if scope_vars:
+                self._handled_vars.difference_update(scope_vars)
+        return node
+
+class QuantifyVarsRewriter(Rewriter):
+    """
+    Rewrite the model to quantify variables as closely as possible to the affected sub-tasks.
+    """
+
+    def __init__(self, quant: FindQuantificationNodes):
+        super().__init__()
+        self.node_quantifies_vars = quant.node_quantifies_vars
+
+    def handle_logical(self, node: ir.Logical, parent: ir.Node, ctx:Optional[Any]=None) -> ir.Logical:
+        if contains_only_declarable_constraints(node):
+            return node
+
+        new_body = self.walk_list(node.body, node)
+
+        if node.id in self.node_quantifies_vars:
+            vars = self.node_quantifies_vars[node.id]
+            effect_tasks = []
+            inner_tasks = []
+            agg_or_rank_tasks = []
+            for task in new_body:
+                if isinstance(task, ir.Output):
+                    effect_tasks.append(task)
+
+                elif isinstance(task, ir.Update):
+                    effect_tasks.append(task)
+
+                elif isinstance(task, (ir.Aggregate, ir.Rank)):
+                    # TODO: QB shouldn't generate multiple aggregate tasks, but unit tests written
+                    # in IR directly may do so and the flatten pass doesn't split them yet.
+                    if len(agg_or_rank_tasks) > 0:
+                        print(f"Multiple aggregate/rank tasks found: {agg_or_rank_tasks} and {task}")
+                    agg_or_rank_tasks.append(task)
+
+                else:
+                    inner_tasks.append(task)
+
+            if vars:
+                var_list = list(vars)
+                var_list.sort(key=lambda var: var.name)
+                if len(inner_tasks) == 1 and isinstance(inner_tasks[0], ir.Logical):
+                    body = f.exists(var_list, inner_tasks[0])
+                else:
+                    body = f.exists(var_list, f.logical(inner_tasks))
+                # If the logical is describing an aggregate/rank, confine the existential to
+                # the aggregate/rank's body, by wrapping it in another logical.
+                if agg_or_rank_tasks:
+                    body = f.logical([body, *agg_or_rank_tasks])
+                return f.logical([body, *effect_tasks], node.hoisted)
+
+        return node if self._eq_tasks(node.body, new_body) else f.logical(new_body, node.hoisted)
+
+    def handle_not(self, node: ir.Not, parent: ir.Node, ctx:Optional[Any]=None) -> ir.Not:
+        new_task = self.walk(node.task)
+
+        if node.id in self.node_quantifies_vars:
+            vars = self.node_quantifies_vars[node.id]
+            return f.not_(f.exists(list(vars), new_task))
+
+        return node if node.task is new_task else f.not_(new_task)
+
+    # To avoid unnecessary cloning of vars in the visitor.
+    def handle_var(self, node: ir.Var, parent: ir.Node, ctx:Optional[Any]=None) -> ir.Var:
+        return node
+
+    def _eq_tasks(self, xs: Tuple[ir.Task, ...], ys: Tuple[ir.Task, ...]) -> bool:
+        if len(xs) != len(ys):
+            return False
+        for x, y in zip(xs, ys):
+            if x is not y:
+                return False
+        return True

v0/relationalai/semantics/lqp/rewrite/splinter.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from typing import Optional, Sequence as PySequence, cast
+
+from v0.relationalai.semantics.metamodel import ir, compiler as c, factory as f, util
+from v0.relationalai.semantics.metamodel.helpers import collect_implicit_vars
+
+class Splinter(c.Pass):
+    """
+    Splits multi-headed rules into multiple rules. Additionally, infers missing Exists tasks.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.name_cache = util.NameCache(start_from_one=True)
+
+    def rewrite(self, model: ir.Model, options:dict={}) -> ir.Model:
+        if isinstance(model.root, ir.Logical):
+            final = []
+            new_relations:list[ir.Relation] = []
+            new_relations.extend(model.relations)
+            for child in model.root.body:
+                new_logicals, relation = self.split(cast(ir.Logical, child))
+                final.extend(new_logicals)
+                if relation:
+                    new_relations.append(relation)
+            return ir.Model(
+                    model.engines,
+                    util.FrozenOrderedSet.from_iterable(new_relations),
+                    model.types,
+                    ir.Logical(
+                        model.root.engine,
+                        model.root.hoisted,
+                        tuple(final)
+                    )
+                )
+        return model
+
+    def split(self, node: ir.Logical) -> tuple[list[ir.Logical], Optional[ir.Relation]]:
+        # Split this logical, which represents a rule, into potentially many logicals, one
+        # for each head (update or output)
+        effects, body = self.split_items(node.body)
+
+        if len(effects) > 1:
+            effects_vars = collect_implicit_vars(*effects)
+            final:list[ir.Logical] = []
+            connection = None
+            if body:
+                # if the node has a body, create a connection, derive the body into the
+                # connection, and then lookup this connection on the other logicals
+                name = self.name_cache.get_name(node.id, "_intermediate")
+                connection = f.relation(name, [f.field(f"f_{i+1}", v.type) for i, v in enumerate(effects_vars)])
+                final.append(f.logical([*body, f.derive(connection, list(effects_vars))]))
+
+            for effect in effects:
+                if connection:
+                    # there's a connection, create a logical that looks up from the connection
+                    # and derives into the effect
+                    lookup = f.lookup(connection, effects_vars.get_list())
+                    final.append(f.logical([lookup, effect]))
+                else:
+                    # if there's no connection, the effect is self contained (probably literals)
+                    final.append(f.logical([effect]))
+            return final, connection
+        return [node], None
+
+
+    def split_items(self, items: PySequence[ir.Task]) -> tuple[list[ir.Task], list[ir.Task]]:
+        effects = []
+        body = []
+        for item in items:
+            if isinstance(item, (ir.Update, ir.Output)):
+                effects.append(item)
+            else:
+                body.append(item)
+        return effects, body