Blog › ICP guides

Flix developer on retainer: Datalog integration, lattice types, inject/query/solve, algebraic effects, effect rows, and functional-Datalog programming on monthly retainer

November 19, 2026 · ~16 min read

A Flix program using Flix’s built-in Datalog engine for a points-to analysis was producing six wrong derived facts per analysis run. The program performed a variable-aliasing analysis using Flix’s fixpoint solver: a PointsTo lattice predicate tracked which heap allocations a program variable could point to, using a PowerSet[Allocation] lattice for the derivation value. The program defined a newtype wrapper enum Variable { case Variable(String) } to distinguish variable names from arbitrary strings. Initial facts were injected into the solver with inject varPointsTo into PointsTo where varPointsTo was a List[(Variable, Allocation)]. The lattice predicate had been declared with type signature PointsTo(; String; PowerSet[Allocation]) — using the bare String type rather than the Variable wrapper for the key parameter. Flix’s Coerce typeclass provides an automatic coercion from a newtype to its underlying type; Variable implements Coerce[Variable, String], so Variable("x") can be coerced to "x". At the inject call site, Flix applied this coercion to convert each Variable key to a String before inserting the fact — the coercion was type-safe and the compiler accepted it without warning. The solver computed the fixed point correctly, but the resulting facts were keyed by unwrapped string values. Subsequent query calls looked up facts using Variable("x") keys against a predicate declared with String keys; the Variable wrapper was not coerced at query time, so the lookup found no matching facts. Six wrong derived facts per analysis run (the analysis returned zero results for every variable rather than the correct points-to sets). The Flix developer on retainer diagnosed the inject/query type mismatch: restructured the PointsTo predicate signature to use Variable as the key type, added explicit Variable("x") wrappers at the three inject call sites that had been passing bare strings, and verified that all query call sites used the same Variable wrapper type. Wrong derived facts per analysis run: 6 → 0.

The work log entry read “fixed wrong Datalog query results, 17h.” It names the symptom and duration. It cannot explain to a client why Flix’s Coerce typeclass applies at inject call sites but not at query call sites (the inject function’s signature accepts a collection whose element types are matched against the declared predicate parameter types; when the element type is Variable and the predicate parameter type is String, Flix infers that a Coerce[Variable, String] instance is available and applies the coercion to make the types match; the coercion is type-safe from the compiler’s perspective, so no warning is produced; but the coercion changes the keys stored in the Datalog database from Variable instances to String instances; at query time, the lookup pattern must exactly match the declared predicate key type, which is String in the database; if the query uses a Variable lookup key, the type system allows the query because Variable is coerceable to String, but the lookup is performed with the Variable value before coercion, which does not match the String keys in the database). It cannot explain why materializing the database with project would have identified the type mismatch (projecting the PointsTo predicate returns facts as List[(String, PowerSet[Allocation])]; comparing the projected key type to the expected Variable type would have made the inject-time coercion visible; adding a project-based assertion early in the debugging process would have reduced the 17-hour audit to a two-hour inspection). The 17 hours of inject/query type consistency audit, Coerce instance interaction analysis, systematic review of all inject call sites to verify that passed types exactly match declared predicate signatures without silent coercion, and database materialization discipline design are invisible in the diff beyond the type annotation change and wrapper additions at three call sites.

Flix Datalog integration: inject, query, solve, project, and lattice type declaration

Flix embeds a complete Datalog sublanguage within functional Flix programs. Datalog rules are expressed using a special syntax that the Flix compiler translates into calls to the built-in fixpoint solver. Initial facts are injected from Flix collections into Datalog predicates using inject; derived facts are computed by the solver using Datalog rules; results are extracted back into Flix data structures using query or project. The pipeline is: (1) create initial fact collections in functional Flix; (2) inject them into a Datalog program; (3) add Datalog rules to derive new facts; (4) solve the program to compute the fixed point; (5) query or project to extract results. The type system enforces that each step in the pipeline uses consistent types, but the Coerce typeclass provides an implicit coercion path that can introduce type mismatches silently between inject and query steps.

Lattice predicates extend Datalog with lattice-valued conclusions. A lattice predicate is declared with a semicolon separating the key parameters from the lattice value: pred PointsTo(; Variable; PowerSet[Allocation]) declares a predicate with key type Variable and lattice value type PowerSet[Allocation]. For each unique key, the solver maintains a lattice element that is the lub (least upper bound) of all lattice values derived for that key. The lattice value type must implement Flix’s Lattice typeclass: instance Lattice[PowerSet[A]] { def bot(): ... def lub(x, y): ... def leq(x, y): ... }. The bot method returns the lattice’s bottom element (the empty set for PowerSet); lub computes the least upper bound (set union for PowerSet); leq computes the partial order relation (subset-or-equal for PowerSet). Fixed-point convergence is guaranteed when the lattice has finite height (no infinite ascending chains); PowerSet[A] for a finite A has finite height equal to the number of elements in A.

The inject varCollection into Pred expression inserts facts from varCollection into predicate Pred. The element type of varCollection must be a tuple matching the predicate’s parameter types (including both key and non-lattice parameters). The retainer rule for inject/query consistency: the type of every element tuple element in every inject call must exactly match the declared predicate parameter type — do not rely on Coerce to bridge the types, because the coercion is one-directional (applied at inject but not at query, in Flix’s current implementation). Use project after solve to materialize all facts for a predicate and compare the key types against expectations: let pts = query db select (k, v) from PointsTo(; k; v); inspect the inferred type of pts; if it is List[(String, PowerSet[Allocation])] when you expected List[(Variable, PowerSet[Allocation])], the inject coercion has changed the key type.

Flix algebraic effects: effect declarations, fun vs ctl handler clauses, and resume continuation threading

Flix’s algebraic effect system allows user-defined computational effects beyond the built-in effects. An effect is declared with eff EffName { def operation(args): retType } and handled with a handler block: run { ... } with handler EffName { def operation(args)(resume): ... }. Inside the computation block, do EffName.operation(args) performs the operation. The handler intercepts the operation and decides how to continue the computation using the resume continuation. Two clause forms are available for handler methods: fun clauses and ctl clauses, and the choice between them determines whether the handler has access to the continuation.

A fun clause handler method has no resume parameter; the handler computes a return value and the computation continues automatically as if the operation had returned that value. Fun clause handlers are equivalent to simple function substitution for the effect operation; they are the appropriate choice when the handler does not need to inspect or manipulate the continuation, and Flix can optimize fun clause handlers into inlined function calls in some cases. A ctl clause handler method receives the resume continuation as an explicit parameter; the handler can call resume(value) zero or more times, passing a return value to the suspended computation. Calling resume once continues the computation normally; calling it zero times aborts the computation from the operation site; calling it more than once runs the continuation multiple times, which is the basis for non-determinism and list comprehension patterns. The critical distinction: a fun clause handler has no access to the continuation, so any state that the handler accumulates is local to the handler invocation; when the operation is called again in the same computation, a new handler invocation starts with fresh local state. If the handler needs to accumulate state across multiple operations (collecting all log entries, for example), a ctl clause must be used to thread state through the resume calls.

The most common Flix algebraic effect retainer bug is a fun clause where a ctl clause was required. Symptom: a log effect with an emit(msg) operation; handler uses a fun clause that appends to a local list; the list contains only the last emitted message, not all of them; or the list is empty because the local append in each fun invocation is discarded after the invocation ends. The fix: restructure to a ctl clause that threads the accumulator through resume: def emit(msg)(resume): ... let acc = resume(()); acc with msg prepended. The continuation returns the result of the remaining computation (typically the accumulated list from subsequent emit calls); the handler prepends the current message to that result. This requires understanding that resume(()) returns whatever the remaining computation produces after the current emit, which in a ctl-threaded log handler is the list of all subsequent messages — so the final result is the current message prepended to the list of subsequent messages, which by induction equals the list of all messages in order.

Flix effect rows, regions, channels, and Magnus Madsen’s functional-Datalog design

Flix’s type system tracks computational effects in every function’s type signature. A function type in Flix is written a -> b \ ef where ef is the effect row of calling the function. The effect row is a set-like type-level collection of effect labels: IO for any I/O, ST[r] for mutable state in region r, Exec for process execution, Net for network access, Random for non-deterministic random values. A function with no effects has effect row Pure (equivalent to the empty set {}). Flix infers effect rows for most functions; the programmer only needs to annotate when the inference needs guidance or when defining interfaces. Effect polymorphism allows a higher-order function to have the same effect row as its function argument: def map(f: a -> b \ ef, l: List[a]): List[b] \ ef says that calling map has the same effect as calling f; if f is pure, map is pure; if f has IO, map has IO.

The region system provides structured, safe mutable state. A region is introduced with region r { ... }; mutable references created inside the region block have type Ref[A, r] where r is the region’s type variable. A Ref[A, r] cannot escape the region block: its type contains the region variable r, which is scoped to the region { ... } block, so the Flix type system prevents the reference from being returned or stored in a data structure that outlives the region. Operations on a Ref have effect ST[r]; code outside the region cannot have this effect without access to r. The retainer pattern: when a computation needs mutable state, introduce a region, create Refs inside it, perform all mutations, and extract the final value before the region closes; the extracted value must have a type that does not mention the region variable, which means the value must be immutable (copying out of the Ref into a plain value).

Magnus Madsen at the University of British Columbia designed Flix starting around 2014 with the goal of combining the expressiveness of Datalog for relational reasoning (reachability, type inference, points-to analysis, program dependency analysis) with functional programming (type safety, algebraic data types, higher-order functions) in a single language where both sublanguages share the type system and interact cleanly. Flix compiles to JVM bytecode; JVM interop uses import java.util.HashMap to bring JVM types into scope and HashMap.put(map, k, v) syntax for method invocation; JVM method calls have IO effect because they may mutate external state. Flix’s module system uses mod ModuleName { ... } for declarations and use ModuleName.{foo, bar} for imports; the module system is hierarchical (nested mods) and namespace-flat within a module. Flix’s standard library includes collections (List, Set, Map, Vector), Datalog utilities, channels, concurrent processes (spawn), and algebraic effects. Flix is closest in design philosophy to Haskell (pure functional programming with effect tracking) and to Scala (JVM compilation, strong type system), but its Datalog integration and algebraic effect system distinguish it from both.

How HourTab tracks Flix developer retainer hours

Flix Datalog retainer work shares the invisible-work problem of all type-level programming retainers, compounded by Flix’s silent Coerce application at inject call sites — the bug produces empty query results rather than wrong values, which presents as a missing-facts problem to the application layer and misdirects debugging toward the Datalog rules (which are correct) rather than the inject/query type consistency (where the problem lives). A Datalog inject/query type consistency repair is a diff with a changed predicate type annotation and wrapper additions at a handful of inject call sites; the value is correct query results for all lattice key lookups, systematic verification that no inject call site relies on implicit Coerce to bridge inject and query types, and a project-based assertion discipline that materializes the database after solving and confirms key types before the first query.

HourTab gives Flix developers a public retainer-hours URL they send to clients — typically research groups using Flix for program analysis pipelines, language tooling teams building type inference engines with Flix’s Datalog solver, and organizations using Flix’s algebraic effect system for effect-tracked business logic. For Flix retainers, each work log entry should name the mechanism (Datalog inject/query type consistency; lattice type signature design; inject call site type audit; Coerce instance interaction analysis; project-based database materialization; algebraic effect declaration; fun vs ctl handler clause design; resume continuation threading; effect row polymorphism; run region scope for ST effects; Ref region lifetime analysis; JVM interop import and invoke; module system design), the specific predicates, lattice types, inject call sites, effect handlers, and resume chains involved in the bug, and the before/after metric. Flix retainers are often compared to Haskell developer retainers for the shared pure functional programming foundation with explicit effect tracking and to Scala developer retainers for the shared JVM target and strong type system discipline. HourTab’s work log makes the inject/query type audit, Coerce instance interaction analysis, and inject call site wrapper addition discipline visible to clients who would otherwise see only the symptom — six wrong derived facts per analysis run — and not understand why the fix required understanding Flix’s Coerce typeclass application at inject vs query call sites, auditing every inject call site for type consistency with the declared predicate signature, and adding explicit type wrappers to prevent the silent coercion that shifted the database key type.

FAQ: Flix developer retainers