eyeling 1.6.14 → 1.6.16

package/README.md

@@ -103,16 +103,16 @@ npm run test:packlist
 - `test:package` does a “real consumer” smoke test: `npm pack` → install tarball into a temp project → run API + CLI + examples.
 - `test:packlist` sanity-checks what will be published in the npm tarball (and the CLI shebang/bin wiring).
 
-### Run a single file
+### Usage
 
-From the repo root:
-
-```bash
-# Option 1: use the shebang (Unix-like)
-./eyeling.js examples/socrates.n3
+```
+Usage: eyeling.js [options] <file.n3>
 
-# Option 2: explicit node
-node eyeling.js examples/socrates.n3
+Options:
+  -h, --help              Show this help and exit.
+  -v, --version           Print version and exit.
+  -p, --proof-comments    Enable proof explanations.
+  -n, --no-proof-comments Disable proof explanations (default).
 ```
 
 By default, `eyeling`:
@@ -122,17 +122,6 @@ By default, `eyeling`:
 3. prints only **newly derived forward facts** (not the original input facts)
 4. prints a compact per-triple explanation as `#` comments (can be disabled)
 
-### Options
-
-```bash
-node eyeling.js --version
-node eyeling.js -v
-
-# Disable proof comments (print only derived triples)
-node eyeling.js --no-proof-comments examples/socrates.n3
-node eyeling.js -n examples/socrates.n3
-```
-
 ## What output do I get?
 
 For each newly derived triple, `eyeling` prints:

package/eyeling.js

@@ -75,7 +75,7 @@ const skolemCache = new Map();
 const jsonPointerCache = new Map();
 
 // Controls whether human-readable proof comments are printed.
-let proofCommentsEnabled = true;
+let proofCommentsEnabled = false;
 
 // ----------------------------------------------------------------------------
 // Deterministic time support
@@ -2041,6 +2041,16 @@ function unifyFormulaTriples(xs, ys, subst) {
 }
 
 function unifyTerm(a, b, subst) {
+  return unifyTermWithOptions(a, b, subst, { boolValueEq: true, intDecimalEq: false });
+}
+
+function unifyTermListAppend(a, b, subst) {
+  // Keep list:append behavior: allow integer<->decimal exact equality,
+  // but do NOT add boolean-value equivalence (preserves current semantics).
+  return unifyTermWithOptions(a, b, subst, { boolValueEq: false, intDecimalEq: true });
+}
+
+function unifyTermWithOptions(a, b, subst, opts) {
   a = applySubstTerm(a, subst);
   b = applySubstTerm(b, subst);
 
@@ -2054,9 +2064,8 @@ function unifyTerm(a, b, subst) {
     s2[v] = t;
     return s2;
   }
-
   if (b instanceof Var) {
-    return unifyTerm(b, a, subst);
+    return unifyTermWithOptions(b, a, subst, opts);
   }
 
   // Exact matches
@@ -2064,25 +2073,25 @@ function unifyTerm(a, b, subst) {
   if (a instanceof Literal && b instanceof Literal && a.value === b.value) return { ...subst };
   if (a instanceof Blank && b instanceof Blank && a.label === b.label) return { ...subst };
 
-  // String-literal match (RDF 1.1): treat plain strings and xsd:string as equal (but not @lang)
+  // Plain string vs xsd:string equivalence
   if (a instanceof Literal && b instanceof Literal) {
     if (literalsEquivalentAsXsdString(a.value, b.value)) return { ...subst };
   }
 
-  // Boolean-value match: treat untyped true/false tokens and xsd:boolean as equal.
-  if (a instanceof Literal && b instanceof Literal) {
+  // Boolean-value equivalence (ONLY for normal unifyTerm)
+  if (opts.boolValueEq && a instanceof Literal && b instanceof Literal) {
     const ai = parseBooleanLiteralInfo(a);
     const bi = parseBooleanLiteralInfo(b);
     if (ai && bi && ai.value === bi.value) return { ...subst };
   }
 
-  // Numeric-value match for literals, BUT ONLY when datatypes agree (or infer to agree)
+  // Numeric-value match:
+  // - always allow equality when datatype matches (existing behavior)
+  // - optionally allow integer<->decimal exact equality (list:append only)
   if (a instanceof Literal && b instanceof Literal) {
     const ai = parseNumericLiteralInfo(a);
     const bi = parseNumericLiteralInfo(b);
-
     if (ai && bi) {
-      // same datatype: keep existing behavior
       if (ai.dt === bi.dt) {
         if (ai.kind === 'bigint' && bi.kind === 'bigint') {
           if (ai.value === bi.value) return { ...subst };
@@ -2092,101 +2101,18 @@ function unifyTerm(a, b, subst) {
           if (!Number.isNaN(an) && !Number.isNaN(bn) && an === bn) return { ...subst };
         }
       }
-    }
-  }
-
-  // Open list vs concrete list
-  if (a instanceof OpenListTerm && b instanceof ListTerm) {
-    return unifyOpenWithList(a.prefix, a.tailVar, b.elems, subst);
-  }
-  if (a instanceof ListTerm && b instanceof OpenListTerm) {
-    return unifyOpenWithList(b.prefix, b.tailVar, a.elems, subst);
-  }
-
-  // Open list vs open list (same tail var)
-  if (a instanceof OpenListTerm && b instanceof OpenListTerm) {
-    if (a.tailVar !== b.tailVar || a.prefix.length !== b.prefix.length) return null;
-    let s2 = { ...subst };
-    for (let i = 0; i < a.prefix.length; i++) {
-      s2 = unifyTerm(a.prefix[i], b.prefix[i], s2);
-      if (s2 === null) return null;
-    }
-    return s2;
-  }
-
-  // List terms
-  if (a instanceof ListTerm && b instanceof ListTerm) {
-    if (a.elems.length !== b.elems.length) return null;
-    let s2 = { ...subst };
-    for (let i = 0; i < a.elems.length; i++) {
-      s2 = unifyTerm(a.elems[i], b.elems[i], s2);
-      if (s2 === null) return null;
-    }
-    return s2;
-  }
 
-  // Formulas:
-  // 1) If they are alpha-equivalent, succeed without leaking internal bindings.
-  // 2) Otherwise fall back to full unification (may bind vars).
-  if (a instanceof FormulaTerm && b instanceof FormulaTerm) {
-    if (alphaEqFormulaTriples(a.triples, b.triples)) return { ...subst };
-    return unifyFormulaTriples(a.triples, b.triples, subst);
-  }
-  return null;
-}
-
-function unifyTermListAppend(a, b, subst) {
-  a = applySubstTerm(a, subst);
-  b = applySubstTerm(b, subst);
-
-  // Variable binding (same as unifyTerm)
-  if (a instanceof Var) {
-    const v = a.name;
-    const t = b;
-    if (t instanceof Var && t.name === v) return { ...subst };
-    if (containsVarTerm(t, v)) return null;
-    const s2 = { ...subst };
-    s2[v] = t;
-    return s2;
-  }
-  if (b instanceof Var) return unifyTermListAppend(b, a, subst);
-
-  // Exact matches
-  if (a instanceof Iri && b instanceof Iri && a.value === b.value) return { ...subst };
-  if (a instanceof Literal && b instanceof Literal && a.value === b.value) return { ...subst };
-  if (a instanceof Blank && b instanceof Blank && a.label === b.label) return { ...subst };
-
-  // Plain string vs xsd:string equivalence
-  if (a instanceof Literal && b instanceof Literal) {
-    if (literalsEquivalentAsXsdString(a.value, b.value)) return { ...subst };
-  }
-
-  // Numeric match: same-dt OR integer<->decimal exact equality (for list:append only)
-  if (a instanceof Literal && b instanceof Literal) {
-    const ai = parseNumericLiteralInfo(a);
-    const bi = parseNumericLiteralInfo(b);
-    if (ai && bi) {
-      // same datatype
-      if (ai.dt === bi.dt) {
-        if (ai.kind === 'bigint' && bi.kind === 'bigint') {
-          if (ai.value === bi.value) return { ...subst };
-        } else {
-          const an = ai.kind === 'bigint' ? Number(ai.value) : ai.value;
-          const bn = bi.kind === 'bigint' ? Number(bi.value) : bi.value;
-          if (!Number.isNaN(an) && !Number.isNaN(bn) && an === bn) return { ...subst };
-        }
-      }
-
-      // integer <-> decimal exact equality
-      const intDt = XSD_NS + 'integer';
-      const decDt = XSD_NS + 'decimal';
-      if ((ai.dt === intDt && bi.dt === decDt) || (ai.dt === decDt && bi.dt === intDt)) {
-        const intInfo = ai.dt === intDt ? ai : bi;
-        const decInfo = ai.dt === decDt ? ai : bi;
-        const dec = parseXsdDecimalToBigIntScale(decInfo.lexStr);
-        if (dec) {
-          const scaledInt = intInfo.value * pow10n(dec.scale);
-          if (scaledInt === dec.num) return { ...subst };
+      if (opts.intDecimalEq) {
+        const intDt = XSD_NS + 'integer';
+        const decDt = XSD_NS + 'decimal';
+        if ((ai.dt === intDt && bi.dt === decDt) || (ai.dt === decDt && bi.dt === intDt)) {
+          const intInfo = ai.dt === intDt ? ai : bi; // bigint
+          const decInfo = ai.dt === decDt ? ai : bi; // number + lexStr
+          const dec = parseXsdDecimalToBigIntScale(decInfo.lexStr);
+          if (dec) {
+            const scaledInt = intInfo.value * pow10n(dec.scale);
+            if (scaledInt === dec.num) return { ...subst };
+          }
         }
       }
     }
@@ -2205,7 +2131,7 @@ function unifyTermListAppend(a, b, subst) {
     if (a.tailVar !== b.tailVar || a.prefix.length !== b.prefix.length) return null;
     let s2 = { ...subst };
     for (let i = 0; i < a.prefix.length; i++) {
-      s2 = unifyTermListAppend(a.prefix[i], b.prefix[i], s2);
+      s2 = unifyTermWithOptions(a.prefix[i], b.prefix[i], s2, opts);
       if (s2 === null) return null;
     }
     return s2;
@@ -2216,7 +2142,7 @@ function unifyTermListAppend(a, b, subst) {
     if (a.elems.length !== b.elems.length) return null;
     let s2 = { ...subst };
     for (let i = 0; i < a.elems.length; i++) {
-      s2 = unifyTermListAppend(a.elems[i], b.elems[i], s2);
+      s2 = unifyTermWithOptions(a.elems[i], b.elems[i], s2, opts);
       if (s2 === null) return null;
     }
     return s2;
@@ -2886,14 +2812,7 @@ function parseNumOrDuration(t) {
 
 function formatDurationLiteralFromSeconds(secs) {
   const neg = secs < 0;
-  const absSecs = Math.abs(secs);
-  const days = Math.round(absSecs / 86400.0);
-  const lex = neg ? `" -P${days}D"` : `"P${days}D"`;
-  const cleanLex = neg ? `" -P${days}D"` : `"P${days}D"`; // minor detail; we just follow shape
-  const lex2 = neg ? `" -P${days}D"` : `"P${days}D"`;
-  const actualLex = neg ? `" -P${days}D"` : `"P${days}D"`;
-  // keep simpler, no spaces:
-  const finalLex = neg ? `" -P${days}D"` : `"P${days}D"`;
+  const days = Math.round(Math.abs(secs) / 86400.0);
   const literalLex = neg ? `"-P${days}D"` : `"P${days}D"`;
   return new Literal(`${literalLex}^^<${XSD_NS}duration>`);
 }
@@ -3091,6 +3010,38 @@ function evalUnaryMathRel(g, subst, forwardFn, inverseFn /* may be null */) {
   return [];
 }
 
+function evalListFirstLikeBuiltin(sTerm, oTerm, subst) {
+  if (!(sTerm instanceof ListTerm)) return [];
+  if (!sTerm.elems.length) return [];
+  const first = sTerm.elems[0];
+  const s2 = unifyTerm(oTerm, first, subst);
+  return s2 !== null ? [s2] : [];
+}
+
+function evalListRestLikeBuiltin(sTerm, oTerm, subst) {
+  // Closed list: (a b c) -> (b c)
+  if (sTerm instanceof ListTerm) {
+    if (!sTerm.elems.length) return [];
+    const rest = new ListTerm(sTerm.elems.slice(1));
+    const s2 = unifyTerm(oTerm, rest, subst);
+    return s2 !== null ? [s2] : [];
+  }
+
+  // Open list: (a b ... ?T) -> (b ... ?T)
+  if (sTerm instanceof OpenListTerm) {
+    if (!sTerm.prefix.length) return [];
+    if (sTerm.prefix.length === 1) {
+      const s2 = unifyTerm(oTerm, new Var(sTerm.tailVar), subst);
+      return s2 !== null ? [s2] : [];
+    }
+    const rest = new OpenListTerm(sTerm.prefix.slice(1), sTerm.tailVar);
+    const s2 = unifyTerm(oTerm, rest, subst);
+    return s2 !== null ? [s2] : [];
+  }
+
+  return [];
+}
+
 // ============================================================================
 // Backward proof & builtins mutual recursion — declarations first
 // ============================================================================
@@ -3785,79 +3736,18 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen) {
     return [];
   }
 
-  // list:first
+  // list:first and rdf:first
   // true iff $s is a list and $o is the first member of that list.
   // Schema: $s+ list:first $o-
-  if (g.p instanceof Iri && g.p.value === LIST_NS + 'first') {
-    if (!(g.s instanceof ListTerm)) return [];
-    if (!g.s.elems.length) return [];
-    const first = g.s.elems[0];
-    const s2 = unifyTerm(g.o, first, subst);
-    return s2 !== null ? [s2] : [];
+  if (g.p instanceof Iri && (g.p.value === LIST_NS + 'first' || g.p.value === RDF_NS + 'first')) {
+    return evalListFirstLikeBuiltin(g.s, g.o, subst);
   }
 
-  // list:rest
+  // list:rest and rdf:rest
   // true iff $s is a (non-empty) list and $o is the rest (tail) of that list.
   // Schema: $s+ list:rest $o-
-  if (g.p instanceof Iri && g.p.value === LIST_NS + 'rest') {
-    // Closed list: (a b c) -> (b c)
-    if (g.s instanceof ListTerm) {
-      if (!g.s.elems.length) return [];
-      const rest = new ListTerm(g.s.elems.slice(1));
-      const s2 = unifyTerm(g.o, rest, subst);
-      return s2 !== null ? [s2] : [];
-    }
-
-    // Open list: (a b ... ?T) -> (b ... ?T)
-    if (g.s instanceof OpenListTerm) {
-      if (!g.s.prefix.length) return []; // can't compute rest without a known head
-
-      if (g.s.prefix.length === 1) {
-        // (a ... ?T) rest is exactly ?T
-        const s2 = unifyTerm(g.o, new Var(g.s.tailVar), subst);
-        return s2 !== null ? [s2] : [];
-      }
-
-      const rest = new OpenListTerm(g.s.prefix.slice(1), g.s.tailVar);
-      const s2 = unifyTerm(g.o, rest, subst);
-      return s2 !== null ? [s2] : [];
-    }
-
-    return [];
-  }
-
-  // rdf:first (alias of list:first)
-  // Schema: $s+ rdf:first $o-
-  if (g.p instanceof Iri && g.p.value === RDF_NS + 'first') {
-    if (!(g.s instanceof ListTerm)) return [];
-    if (!g.s.elems.length) return [];
-    const first = g.s.elems[0];
-    const s2 = unifyTerm(g.o, first, subst);
-    return s2 !== null ? [s2] : [];
-  }
-
-  // rdf:rest (alias of list:rest)
-  // Schema: $s+ rdf:rest $o-
-  if (g.p instanceof Iri && g.p.value === RDF_NS + 'rest') {
-    // Closed list: (a b c) -> (b c)
-    if (g.s instanceof ListTerm) {
-      if (!g.s.elems.length) return [];
-      const rest = new ListTerm(g.s.elems.slice(1));
-      const s2 = unifyTerm(g.o, rest, subst);
-      return s2 !== null ? [s2] : [];
-    }
-    // Open list: (a b ... ?T) -> (b ... ?T)
-    if (g.s instanceof OpenListTerm) {
-      if (!g.s.prefix.length) return [];
-      if (g.s.prefix.length === 1) {
-        const s2 = unifyTerm(g.o, new Var(g.s.tailVar), subst);
-        return s2 !== null ? [s2] : [];
-      }
-      const rest = new OpenListTerm(g.s.prefix.slice(1), g.s.tailVar);
-      const s2 = unifyTerm(g.o, rest, subst);
-      return s2 !== null ? [s2] : [];
-    }
-    return [];
+  if (g.p instanceof Iri && (g.p.value === LIST_NS + 'rest' || g.p.value === RDF_NS + 'rest')) {
+    return evalListRestLikeBuiltin(g.s, g.o, subst);
   }
 
   // list:iterate
@@ -5065,134 +4955,121 @@ function forwardChain(facts, forwardRules, backRules) {
 
   function runFixpoint() {
     let anyChange = false;
+
     while (true) {
       let changed = false;
 
-      while (true) {
-        let changed = false;
-
-        for (let i = 0; i < forwardRules.length; i++) {
-          const r = forwardRules[i];
-          const empty = {};
-          const visited = [];
+      for (let i = 0; i < forwardRules.length; i++) {
+        const r = forwardRules[i];
+        const empty = {};
+        const visited = [];
+        const sols = proveGoals(r.premise.slice(), empty, facts, backRules, 0, visited, varGen);
 
-          const sols = proveGoals(r.premise.slice(), empty, facts, backRules, 0, visited, varGen);
+        // Inference fuse
+        if (r.isFuse && sols.length) {
+          console.log('# Inference fuse triggered: a { ... } => false. rule fired.');
+          process.exit(2);
+        }
 
-          // Inference fuse
-          if (r.isFuse && sols.length) {
-            console.log('# Inference fuse triggered: a { ... } => false. rule fired.');
-            process.exit(2);
-          }
+        for (const s of sols) {
+          // IMPORTANT: one skolem map per *rule firing*
+          const skMap = {};
+          const instantiatedPremises = r.premise.map((b) => applySubstTriple(b, s));
+          const fireKey = firingKey(i, instantiatedPremises);
+
+          for (const cpat of r.conclusion) {
+            const instantiated = applySubstTriple(cpat, s);
+
+            const isFwRuleTriple =
+              isLogImplies(instantiated.p) &&
+              ((instantiated.s instanceof FormulaTerm && instantiated.o instanceof FormulaTerm) ||
+                (instantiated.s instanceof Literal && instantiated.s.value === 'true' && instantiated.o instanceof FormulaTerm) ||
+                (instantiated.s instanceof FormulaTerm && instantiated.o instanceof Literal && instantiated.o.value === 'true'));
+
+            const isBwRuleTriple =
+              isLogImpliedBy(instantiated.p) &&
+              ((instantiated.s instanceof FormulaTerm && instantiated.o instanceof FormulaTerm) ||
+                (instantiated.s instanceof FormulaTerm && instantiated.o instanceof Literal && instantiated.o.value === 'true') ||
+                (instantiated.s instanceof Literal && instantiated.s.value === 'true' && instantiated.o instanceof FormulaTerm));
+
+            if (isFwRuleTriple || isBwRuleTriple) {
+              if (!hasFactIndexed(facts, instantiated)) {
+                factList.push(instantiated);
+                pushFactIndexed(facts, instantiated);
+                derivedForward.push(new DerivedFact(instantiated, r, instantiatedPremises.slice(), { ...s }));
+                changed = true;
+              }
 
-          for (const s of sols) {
-            // IMPORTANT: one skolem map per *rule firing* so head blank nodes
-            // (e.g., from [ :p ... ; :q ... ]) stay connected across all head triples.
-            const skMap = {};
-            const instantiatedPremises = r.premise.map((b) => applySubstTriple(b, s));
-            const fireKey = firingKey(i, instantiatedPremises);
-
-            for (const cpat of r.conclusion) {
-              const instantiated = applySubstTriple(cpat, s);
-
-              const isFwRuleTriple =
-                isLogImplies(instantiated.p) &&
-                ((instantiated.s instanceof FormulaTerm && instantiated.o instanceof FormulaTerm) ||
-                  (instantiated.s instanceof Literal && instantiated.s.value === 'true' && instantiated.o instanceof FormulaTerm) ||
-                  (instantiated.s instanceof FormulaTerm && instantiated.o instanceof Literal && instantiated.o.value === 'true'));
-
-              const isBwRuleTriple =
-                isLogImpliedBy(instantiated.p) &&
-                ((instantiated.s instanceof FormulaTerm && instantiated.o instanceof FormulaTerm) ||
-                  (instantiated.s instanceof FormulaTerm && instantiated.o instanceof Literal && instantiated.o.value === 'true') ||
-                  (instantiated.s instanceof Literal && instantiated.s.value === 'true' && instantiated.o instanceof FormulaTerm));
-
-              if (isFwRuleTriple || isBwRuleTriple) {
-                if (!hasFactIndexed(facts, instantiated)) {
-                  factList.push(instantiated);
-                  pushFactIndexed(facts, instantiated);
-                  derivedForward.push(
-                    new DerivedFact(instantiated, r, instantiatedPremises.slice(), {
-                      ...s,
-                    }),
+              // Promote rule-producing triples to live rules, treating literal true as {}.
+              const left =
+                instantiated.s instanceof FormulaTerm
+                  ? instantiated.s.triples
+                  : instantiated.s instanceof Literal && instantiated.s.value === 'true'
+                    ? []
+                    : null;
+
+              const right =
+                instantiated.o instanceof FormulaTerm
+                  ? instantiated.o.triples
+                  : instantiated.o instanceof Literal && instantiated.o.value === 'true'
+                    ? []
+                    : null;
+
+              if (left !== null && right !== null) {
+                if (isFwRuleTriple) {
+                  const [premise0, conclusion] = liftBlankRuleVars(left, right);
+                  const premise = reorderPremiseForConstraints(premise0);
+                  const headBlankLabels = collectBlankLabelsInTriples(conclusion);
+                  const newRule = new Rule(premise, conclusion, true, false, headBlankLabels);
+
+                  const already = forwardRules.some(
+                    (rr) =>
+                      rr.isForward === newRule.isForward &&
+                      rr.isFuse === newRule.isFuse &&
+                      triplesListEqual(rr.premise, newRule.premise) &&
+                      triplesListEqual(rr.conclusion, newRule.conclusion),
                   );
-                  changed = true;
-                }
-
-                // Promote rule-producing triples to live rules, treating literal true as {}.
-                const left =
-                  instantiated.s instanceof FormulaTerm
-                    ? instantiated.s.triples
-                    : instantiated.s instanceof Literal && instantiated.s.value === 'true'
-                      ? []
-                      : null;
-
-                const right =
-                  instantiated.o instanceof FormulaTerm
-                    ? instantiated.o.triples
-                    : instantiated.o instanceof Literal && instantiated.o.value === 'true'
-                      ? []
-                      : null;
-
-                if (left !== null && right !== null) {
-                  if (isFwRuleTriple) {
-                    const [premise0, conclusion] = liftBlankRuleVars(left, right);
-                    const premise = reorderPremiseForConstraints(premise0);
-
-                    const headBlankLabels = collectBlankLabelsInTriples(conclusion);
-                    const newRule = new Rule(premise, conclusion, true, false, headBlankLabels);
-
-                    const already = forwardRules.some(
-                      (rr) =>
-                        rr.isForward === newRule.isForward &&
-                        rr.isFuse === newRule.isFuse &&
-                        triplesListEqual(rr.premise, newRule.premise) &&
-                        triplesListEqual(rr.conclusion, newRule.conclusion),
-                    );
-                    if (!already) forwardRules.push(newRule);
-                  } else if (isBwRuleTriple) {
-                    const [premise, conclusion] = liftBlankRuleVars(right, left);
-
-                    const headBlankLabels = collectBlankLabelsInTriples(conclusion);
-                    const newRule = new Rule(premise, conclusion, false, false, headBlankLabels);
-
-                    const already = backRules.some(
-                      (rr) =>
-                        rr.isForward === newRule.isForward &&
-                        rr.isFuse === newRule.isFuse &&
-                        triplesListEqual(rr.premise, newRule.premise) &&
-                        triplesListEqual(rr.conclusion, newRule.conclusion),
-                    );
-                    if (!already) {
-                      backRules.push(newRule);
-                      indexBackRule(backRules, newRule);
-                    }
+                  if (!already) forwardRules.push(newRule);
+                } else if (isBwRuleTriple) {
+                  const [premise, conclusion] = liftBlankRuleVars(right, left);
+                  const headBlankLabels = collectBlankLabelsInTriples(conclusion);
+                  const newRule = new Rule(premise, conclusion, false, false, headBlankLabels);
+
+                  const already = backRules.some(
+                    (rr) =>
+                      rr.isForward === newRule.isForward &&
+                      rr.isFuse === newRule.isFuse &&
+                      triplesListEqual(rr.premise, newRule.premise) &&
+                      triplesListEqual(rr.conclusion, newRule.conclusion),
+                  );
+                  if (!already) {
+                    backRules.push(newRule);
+                    indexBackRule(backRules, newRule);
                   }
                 }
-
-                continue; // skip normal fact handling
               }
 
-              // Only skolemize blank nodes that occur explicitly in the rule head
-              const inst = skolemizeTripleForHeadBlanks(instantiated, r.headBlankLabels, skMap, skCounter, fireKey, headSkolemCache);
+              continue; // skip normal fact handling
+            }
 
-              if (!isGroundTriple(inst)) continue;
-              if (hasFactIndexed(facts, inst)) continue;
+            // Only skolemize blank nodes that occur explicitly in the rule head
+            const inst = skolemizeTripleForHeadBlanks(instantiated, r.headBlankLabels, skMap, skCounter, fireKey, headSkolemCache);
 
-              factList.push(inst);
-              pushFactIndexed(facts, inst);
+            if (!isGroundTriple(inst)) continue;
+            if (hasFactIndexed(facts, inst)) continue;
 
-              derivedForward.push(new DerivedFact(inst, r, instantiatedPremises.slice(), { ...s }));
-              changed = true;
-            }
+            factList.push(inst);
+            pushFactIndexed(facts, inst);
+            derivedForward.push(new DerivedFact(inst, r, instantiatedPremises.slice(), { ...s }));
+            changed = true;
           }
         }
-
-        if (!changed) break;
       }
 
-      if (changed) anyChange = true;
       if (!changed) break;
+      anyChange = true;
     }
+
     return anyChange;
   }
 
@@ -5558,7 +5435,6 @@ function localIsoDateTimeString(d) {
 // ============================================================================
 // CLI entry point
 // ============================================================================
-
 function main() {
   // Drop "node" and script name; keep only user-provided args
   const argv = process.argv.slice(2);
@@ -5566,6 +5442,19 @@ function main() {
   // --------------------------------------------------------------------------
   // Global options
   // --------------------------------------------------------------------------
+  // --help / -h: print help and exit
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log(
+      'Usage: eyeling.js [options] <file.n3>\n' +
+        '\n' +
+        'Options:\n' +
+        '  -h, --help              Show this help and exit.\n' +
+        '  -v, --version           Print version and exit.\n' +
+        '  -p, --proof-comments    Enable proof explanations.\n' +
+        '  -n, --no-proof-comments Disable proof explanations (default).\n',
+    );
+    process.exit(0);
+  }
 
   // --version / -v: print version and exit
   if (argv.includes('--version') || argv.includes('-v')) {
@@ -5573,7 +5462,13 @@ function main() {
     process.exit(0);
   }
 
-  // --no-proof-comments / -n: disable proof explanations
+  // --proof-comments / -p: enable proof explanations
+  if (argv.includes('--proof-comments') || argv.includes('-p')) {
+    proofCommentsEnabled = true;
+  }
+
+  // --no-proof-comments / -n: disable proof explanations (default)
+  // Keep this after --proof-comments so -n wins if both are present.
   if (argv.includes('--no-proof-comments') || argv.includes('-n')) {
     proofCommentsEnabled = false;
   }
@@ -5582,9 +5477,16 @@ function main() {
   // Positional args (the N3 file)
   // --------------------------------------------------------------------------
   const positional = argv.filter((a) => !a.startsWith('-'));
-
   if (positional.length !== 1) {
-    console.error('Usage: eyeling.js [--version|-v] [--no-proof-comments|-n] <file.n3>');
+    console.error(
+      'Usage: eyeling.js [options] <file.n3>\n' +
+        '\n' +
+        'Options:\n' +
+        '  -h, --help              Show this help and exit.\n' +
+        '  -v, --version           Print version and exit.\n' +
+        '  -p, --proof-comments    Enable proof explanations.\n' +
+        '  -n, --no-proof-comments Disable proof explanations (default).\n',
+    );
     process.exit(1);
   }
 
@@ -5603,12 +5505,12 @@ function main() {
   const [prefixes, triples, frules, brules] = parser.parseDocument();
   // console.log(JSON.stringify([prefixes, triples, frules, brules], null, 2));
 
-  // Build internal ListTerm values from rdf:first/rdf:rest (+ rdf:nil) input triples
+  // Build internal ListTerm values from rdf:first/rdf:rest (+ rdf:nil)
+  // input triples
   materializeRdfLists(triples, frules, brules);
 
   const facts = triples.filter((tr) => isGroundTriple(tr));
   const derived = forwardChain(facts, frules, brules);
-
   const derivedTriples = derived.map((df) => df.fact);
   const usedPrefixes = prefixes.prefixesUsedForOutput(derivedTriples);
 

package/index.js

@@ -1,4 +1,4 @@
-'use strict';
++'use strict';
 
 const fs = require('node:fs');
 const os = require('node:os');
@@ -13,15 +13,23 @@ function reason(opt = {}, n3_input = '') {
 
   // allow passing an args array directly
   if (Array.isArray(opt)) opt = { args: opt };
+  if (opt == null || typeof opt !== 'object') opt = {};
 
   const args = [];
 
   // default: proof comments OFF for API output (machine-friendly)
   // set { proofComments: true } to keep them
+  const proofCommentsSpecified = typeof opt.proofComments === 'boolean' || typeof opt.noProofComments === 'boolean';
+
   const proofComments =
     typeof opt.proofComments === 'boolean' ? opt.proofComments : typeof opt.noProofComments === 'boolean' ? !opt.noProofComments : false;
 
-  if (!proofComments) args.push('--no-proof-comments'); // CLI already supports this :contentReference[oaicite:1]{index=1}
+  // Only pass a flag when the caller explicitly asked.
+  // (CLI default is now: no proof comments.)
+  if (proofCommentsSpecified) {
+    if (proofComments) args.push('--proof-comments');
+    else args.push('--no-proof-comments');
+  }
 
   if (Array.isArray(opt.args)) args.push(...opt.args);
 
@@ -34,10 +42,7 @@ function reason(opt = {}, n3_input = '') {
     fs.writeFileSync(inputFile, n3_input, 'utf8');
 
     const eyelingPath = path.join(__dirname, 'eyeling.js');
-    const res = cp.spawnSync(process.execPath, [eyelingPath, ...args, inputFile], {
-      encoding: 'utf8',
-      maxBuffer,
-    });
+    const res = cp.spawnSync(process.execPath, [eyelingPath, ...args, inputFile], { encoding: 'utf8', maxBuffer });
 
     if (res.error) throw res.error;
     if (res.status !== 0) {
@@ -47,6 +52,7 @@ function reason(opt = {}, n3_input = '') {
       err.stderr = res.stderr;
       throw err;
     }
+
     return res.stdout;
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
@@ -54,5 +60,6 @@ function reason(opt = {}, n3_input = '') {
 }
 
 module.exports = { reason };
+
 // small interop nicety for ESM default import
 module.exports.default = module.exports;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.6.14",
+  "version": "1.6.16",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [