The rule compiler ships in src/compile/. It provides a pure-data IR (5 Term kinds + 4 Goal kinds + Clause + Rule), a lowering pass that produces runtime rule functions, and a per-clause tagged-template DSL for writing rules declaratively.

front-end IR lower.js src/solve.js
───────────────── ───────────── ──────────────────── ─────────────
clause`...` Rule { function (...vars) { rules[name] =
 name ... [fn1, fn2, ...]
 arity }
 clauses[] function (...vars) {
 } ...
 }
 → rules dict

Front-ends emit IR; the runtime never sees IR. Lowering is the only place that knows the runtime rule shape — front-ends and the IR are insulated.

The full design (IR shapes, lowering decisions, the Lit-walker, validation) is in dev-docs/compiler-ir.md. This page is the user-facing reference.

import solve from 'yopl';
import {variable as v} from 'deep6/unify.js';
import assemble from 'deep6/traverse/assemble.js';
import {rule, clause} from 'yopl/compile/clause/index.js';
import {lowerRules} from 'yopl/compile/lower.js';
const rules = lowerRules([rule('member', 2)(clause`(X, [X | _])`, clause`(X, [_ | T]) :- member(X, T)`)]);
const X = v('X');
const list = {value: 1, next: {value: 2, next: {value: 3, next: null}}};
solve(rules, 'member', [list, X], env => console.log(assemble(X, env)));
// 1, 2, 3

Compare to the hand-written encoding in Writing-rules — the compiler emits the right call(...) wrapping automatically and the validator catches arity drift at compile time.

rule(name, arity)(...clauses) returns an IR Rule. Each clause is built via the tagged-template:

clause`HEAD :- BODY` // body optional; bodyless clause is a fact

Interpolation slots (${...}) are auto-wrapped based on whether they appear in argument or goal position:

Arg position (head args, list elements, compound args):

Goal position (body):

The strict "throw on plain object" fence catches a class of bugs where the user intended IR but forgot a constructor (e.g., wrote {name: 'foo', args: []} instead of Compound('foo')).

const i = 5;
clause`(X, 'item${i}')`; // ERROR — the lexer can't close the string across chunks
clause`(X, ${'item' + i})`; // OK — primitive auto-wraps to Lit('item5')

The interpolation must span complete lexemes; tagged-template chunks are lexed independently.

Lit(value) lowers per activation. The walker descends into plain objects and arrays inside the value, and recursively lowers any nested IR node (Var, Wild, Cons, Compound, Lit) with the activation's fresh logic Variables. So an object literal doubles as a pattern matcher and a constructor:

import {rule, clause} from 'yopl/compile/clause/index.js';
import {Lit, Var} from 'yopl/compile/ir.js';
// Match any object whose `age` field is X; bind X.
clause`(${Lit({age: Var('A')})}, A) :- ...`;
// Construct the same shape from a bound A.
clause`(${Lit({age: Var('A')})}, A)`;

The walker is gated on a closed set of IR kind discriminators (var | wildcard | literal | cons | compound), so user objects with a domain kind field (e.g. {kind: 'click', x: 10}) aren't misread.

Maps, Sets, Dates, and Wrap-wrapped values from open() / soft() pass through unchanged — to put logic Variables inside a Map value, build the Map inside a Js body goal where you have direct access to activation Variables.

Imported from yopl/compile/ir.js.

These propagate through Lit(...) so Lit(open({tag: 'a'})) works as expected.

Inline JS goals are built via the Js IR kind (often auto-wrapped from a function in goal position):

type JsFactory = (vars: Record<string, Variable>, sys: ReadonlyArray<Variable>) => GoalFn;

• vars — the activation's user-Variable bindings, keyed by user-var name.
• sys — the choice-point frame slot used by cut(sys).

clause`(X) :- ${({X}) =>
 env =>
 X.isBound(env) && X.get(env) > 0}`;

For symbol-named anonymous Variables (Var() without a name argument), destructure with a computed property name:

const X = Var();
clause`(${X}) :- ${({[X.name]: x}) =>
 env =>
 x.isBound(env)}`;

Imported from yopl/compile/lower.js.

Each clause is walked per activation with fresh logic Variables — the IR is read-only, the lowered values are fresh. The Lit-walker handles nested IR; Compound and Cons walkers handle the structure.

Imported from yopl/compile/validate.js.

Issue kinds: arity-mismatch, call-arity-mismatch, undeclared-var, duplicate-rule, unresolved-rule (opt-in via options.checkRuleReferences).

undeclared-var only fires when Clause.vars is supplied explicitly — front-ends that compute vars from head/body don't trigger it.

The unifyOpts/3 system predicate runs deep6 unification with a per-call options bag, restoring the env's baseline options before the goal returns. From clause source, wrap the bag with Lit({...}):

rule('strictEq', 2)(clause`(X, Y) :- unifyOpts(X, Y, ${Lit({openObjects: false})})`);

Recognized keys: openObjects, openArrays, openMaps, openSets, loose, circular, ignoreFunctions, signedZero, symbols. See rules-system for the full table.

• Home — module overview.
• rules-system — generic logic-programming predicates (unifyOpts, type tests, control flow, higher-order).
• rules-native — JS-native bridge predicates (Array / Map / Set / Date).
• Writing-rules — older hand-written rule encoding (still supported).
• dev-docs/compiler-ir.md — internal design rationale, decisions, practical patterns.