eyeling 1.7.14 → 1.7.16

package/README.md

@@ -8,6 +8,7 @@ A [Notation3 (N3)](https://notation3.org/) reasoner in **JavaScript**.
 - a practical N3/Turtle superset (enough for lots of real rulesets)
 - supports forward (`=>`) + backward (`<=`) chaining over Horn-style rules
 - prints only newly derived forward facts, optionally preceded by compact proof comments
+- can report derived triples as they are produced (streaming callback via `reasonStream`)
 - “pass-only-new” style output (we never want to leak raw input data; backward rules can act like “functions” over raw data)
 - works fully client-side (browser) and in Node.js
 
@@ -16,6 +17,7 @@ A [Notation3 (N3)](https://notation3.org/) reasoner in **JavaScript**.
 Try it here:
 
 - [Eyeling playground](https://eyereasoner.github.io/eyeling/demo)
+- [Eyeling streaming playground](https://eyereasoner.github.io/eyeling/stream)
 
 The playground runs `eyeling` client-side. You can:
 
@@ -72,6 +74,15 @@ const output = eyeling.reason({ proofComments: false }, input);
 console.log(output);
 ```
 
+Streaming (browser/worker, direct `eyeling.js`):
+
+```js
+const { closureN3 } = eyeling.reasonStream(input, {
+  proof: false,
+  onDerived: ({ triple }) => console.log(triple),
+});
+```
+
 Note: the API currently shells out to the bundled `eyeling.js` CLI under the hood (simple + robust).
 
 ## Testing
@@ -216,10 +227,10 @@ Commonly used N3/Turtle features:
 
 - **crypto**: `crypto:md5` `crypto:sha` `crypto:sha256` `crypto:sha512`
 - **list**: `list:append` `list:first` `list:firstRest` `list:in` `list:iterate` `list:last` `list:length` `list:map` `list:member` `list:memberAt` `list:notMember` `list:remove` `list:rest` `list:reverse` `list:sort`
-- **log**: `log:collectAllIn` `log:content` `log:dtlit` `log:equalTo` `log:forAllIn` `log:impliedBy` `log:implies` `log:includes` `log:langlit` `log:notEqualTo` `log:notIncludes` `log:outputString` `log:parsedAsN3` `log:rawType` `log:semantics` `log:semanticsOrError` `log:skolem` `log:uri`
+- **log**: `log:collectAllIn` `log:content` `log:dtlit` `log:equalTo` `log:forAllIn` `log:impliedBy` `log:implies` `log:includes` `log:langlit` `log:notEqualTo` `log:notIncludes` `log:outputString` `log:parsedAsN3` `log:rawType` `log:semantics` `log:semanticsOrError` `log:skolem` `log:trace` `log:uri`
 - **math**: `math:absoluteValue` `math:acos` `math:asin` `math:atan` `math:cos` `math:cosh` `math:degrees` `math:difference` `math:equalTo` `math:exponentiation` `math:greaterThan` `math:integerQuotient` `math:lessThan` `math:negation` `math:notEqualTo` `math:notGreaterThan` `math:notLessThan` `math:product` `math:quotient` `math:remainder` `math:rounded` `math:sin` `math:sinh` `math:sum` `math:tan` `math:tanh`
 - **string**: `string:concatenation` `string:contains` `string:containsIgnoringCase` `string:endsWith` `string:equalIgnoringCase` `string:format` `string:greaterThan` `string:jsonPointer` `string:lessThan` `string:matches` `string:notEqualIgnoringCase` `string:notGreaterThan` `string:notLessThan` `string:notMatches` `string:replace` `string:scrape` `string:startsWith`
-- **time**: `time:day` `time:localTime` `time:minute` `time:month` `time:second` `time:timeZone` `time:year`
+- **time**: `time:day` `time:hour` `time:localTime` `time:minute` `time:month` `time:second` `time:timeZone` `time:year`
 
 ## License
 

package/eyeling-builtins.ttl

@@ -0,0 +1,338 @@
+@prefix ex: <https://eyereasoner.github.io/eyeling/vocab#> .
+@prefix crypto: <http://www.w3.org/2000/10/swap/crypto#> .
+@prefix math: <http://www.w3.org/2000/10/swap/math#> .
+@prefix time: <http://www.w3.org/2000/10/swap/time#> .
+@prefix list: <http://www.w3.org/2000/10/swap/list#> .
+@prefix log: <http://www.w3.org/2000/10/swap/log#> .
+@prefix string: <http://www.w3.org/2000/10/swap/string#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+# ------------------------------------------------------------------------------
+# Builtin catalog (eyeling.js)
+#
+# This file lists the SWAP-style builtins that eyeling.js currently implements
+# in evalBuiltin(), plus rdf:first/rdf:rest aliases for list:first/list:rest.
+#
+# Notes:
+# - ex:kind is intentionally coarse:
+#     ex:Test      = succeeds/fails, no new variable bindings (a "constraint")
+#     ex:Function  = computes an output and may bind variables
+#     ex:Relation  = unification-based, may bind variables
+#     ex:Generator = may yield multiple solutions
+#     ex:IO        = dereferences/parses external content (Node or browser)
+#     ex:Meta      = formula/type/meta-level operations
+#     ex:SideEffect= produces output; does not bind variables
+# - ex:isConstraint corresponds to isConstraintBuiltin(tr) in eyeling.js, with
+#   one suggested addition noted in the comments below.
+# ------------------------------------------------------------------------------
+
+ex:EyelingBuiltinCatalog a ex:Catalog ;
+  rdfs:comment "Builtins implemented by eyeling.js (main branch, raw GitHub URL). Namespaces follow SWAP (crypto/math/time/list/log/string) plus rdf:first/rest aliases." .
+
+ex:Test a ex:Kind .
+ex:Function a ex:Kind .
+ex:Relation a ex:Kind .
+ex:Generator a ex:Kind .
+ex:IO a ex:Kind .
+ex:Meta a ex:Kind .
+ex:SideEffect a ex:Kind .
+
+ex:isConstraint a rdf:Property ;
+  rdfs:comment "True for builtins classified as constraint/test builtins by isConstraintBuiltin(tr) (premise reordering helper)." .
+ex:kind a rdf:Property .
+ex:aliasOf a rdf:Property .
+
+# --- crypto: ---------------------------------------------------------
+
+crypto:sha a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Hash builtin (SHA-1). Computes digest over the subject (string-ish) and unifies/binds the object with the digest." .
+
+crypto:md5 a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Hash builtin (MD5). Computes digest over the subject (string-ish) and unifies/binds the object with the digest." .
+
+crypto:sha256 a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Hash builtin (SHA-256). Computes digest over the subject (string-ish) and unifies/binds the object with the digest." .
+
+crypto:sha512 a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Hash builtin (SHA-512). Computes digest over the subject (string-ish) and unifies/binds the object with the digest." .
+
+# --- math: comparisons (constraint/test) -----------------------------
+
+math:equalTo a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Numeric comparison (=). No bindings; succeeds iff subject and object are numerically equal (supports XSD numeric literals, including special float/double lexicals)." .
+
+math:notEqualTo a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Numeric comparison (!=). No bindings; succeeds iff subject and object are numerically different." .
+
+math:greaterThan a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Numeric comparison (>). No bindings." .
+
+math:lessThan a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Numeric comparison (<). No bindings." .
+
+math:notLessThan a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Numeric comparison (>=). No bindings." .
+
+math:notGreaterThan a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Numeric comparison (<=). No bindings." .
+
+# --- math: arithmetic / numeric functions ----------------------------
+
+math:sum a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Sum of a list of 2+ numeric terms. Binds/unifies object with the total (integer mode uses BigInt when possible)." .
+
+math:product a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Product of a list of 2+ numeric terms. Binds/unifies object with the product (integer mode uses BigInt when possible)." .
+
+math:difference a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Difference of a 2-element list (a b). Supports datetime-datetime -> duration; datetime-duration -> datetime; integer BigInt; otherwise numeric a-b." .
+
+math:quotient a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Quotient of a 2-element list (a b). Binds/unifies object with a/b (guards division by zero and non-finite results)." .
+
+math:integerQuotient a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Integer quotient of (a b), truncating toward zero. Prefers BigInt integer division when possible." .
+
+math:remainder a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Remainder/modulus of (a b). Prefers exact BigInt remainder when possible; otherwise requires integer-valued Numbers." .
+
+math:rounded a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Rounds subject to nearest integer (JS tie-breaking: toward +∞). Binds/unifies object with the rounded integer value." .
+
+math:exponentiation a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Exponentiation. Forward: (base exponent) -> result. Limited inverse: if base is numeric and exponent is a variable, may solve exponent via logs for positive base != 1 and positive result." .
+
+math:absoluteValue a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Absolute value. Computes |s| and unifies/binds object; output datatype follows common numeric datatype selection." .
+
+math:acos a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "acos relation (supports inverse via cos for supported cases)." .
+
+math:asin a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "asin relation (supports inverse via sin for supported cases)." .
+
+math:atan a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "atan relation (supports inverse via tan for supported cases)." .
+
+math:sin a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "sin relation (inverse uses principal asin)." .
+
+math:cos a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "cos relation (inverse uses principal acos)." .
+
+math:tan a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "tan relation (inverse uses principal atan)." .
+
+math:sinh a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "sinh relation (only if JS Math.sinh/Math.asinh exist)." .
+
+math:cosh a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "cosh relation (only if JS Math.cosh/Math.acosh exist)." .
+
+math:tanh a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "tanh relation (only if JS Math.tanh/Math.atanh exist)." .
+
+math:degrees a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Converts radians->degrees; inverse converts degrees->radians." .
+
+math:negation a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Numeric negation; inverse is itself." .
+
+# --- time: -----------------------------------------------------------
+
+time:day a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Extracts day component from xsd:dateTime subject; binds/unifies object with integer token." .
+
+time:hour a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Extracts hour component from xsd:dateTime subject; binds/unifies object with integer token." .
+
+time:minute a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Extracts minute component from xsd:dateTime subject; binds/unifies object with integer token." .
+
+time:month a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Extracts month component from xsd:dateTime subject; binds/unifies object with integer token." .
+
+time:second a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Extracts second component from xsd:dateTime subject; binds/unifies object with integer token." .
+
+time:timeZone a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Extracts timezone suffix from xsd:dateTime subject (e.g., 'Z' or '-05:00'); binds/unifies object with a string literal." .
+
+time:year a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Extracts year component from xsd:dateTime subject; binds/unifies object with integer token." .
+
+time:localTime a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Binds object to 'now' as an xsd:dateTime literal (supports deterministic override via internal setting)." .
+
+# --- list: (plus rdf:first/rest aliases) -----------------------------
+
+list:append a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Concatenates all subject lists; binds/unifies object with the concatenation. If object is a list, can also split." .
+
+list:first a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "First element of a list. Supports open lists in limited cases." .
+
+rdf:first a ex:Builtin ; ex:kind ex:Function ; ex:aliasOf list:first ;
+  rdfs:comment "Alias of list:first (RDF Collections support)." .
+
+list:rest a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Tail of a (non-empty) list. Supports open lists in limited cases." .
+
+rdf:rest a ex:Builtin ; ex:kind ex:Function ; ex:aliasOf list:rest ;
+  rdfs:comment "Alias of list:rest (RDF Collections support)." .
+
+list:iterate a ex:Builtin ; ex:kind ex:Generator ;
+  rdfs:comment "Multi-solution: for each element in the subject list, unifies object with (index value). Index is 0-based." .
+
+list:last a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Unifies/binds object with the last element of the subject list." .
+
+list:memberAt a ex:Builtin ; ex:kind ex:Generator ;
+  rdfs:comment "Multi-solution: (list index) -> value. Index is 0-based; can bind index and/or value." .
+
+list:remove a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Removes all occurrences of an item from a list; requires the item be ground; binds/unifies object with filtered list." .
+
+list:member a ex:Builtin ; ex:kind ex:Generator ;
+  rdfs:comment "Multi-solution: yields each list element as object (unification-based)." .
+
+list:in a ex:Builtin ; ex:kind ex:Generator ;
+  rdfs:comment "Multi-solution: yields each list element as subject (unification-based)." .
+
+list:length a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Length of a list as an integer token. Strict when object is ground (no integer<->decimal equality)." .
+
+list:notMember a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Constraint/test: succeeds iff object does not unify with any element of the subject list. No new bindings." .
+
+list:reverse a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Reverses a list. Supports either direction when one side is a ListTerm." .
+
+list:sort a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Sorts a ground list (numbers numerically when both sides parse as numbers; otherwise lexical; lists lexicographically). Requires all elements ground." .
+
+list:map a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Maps a predicate over a ground input list, collecting *all* solutions for each element and concatenating results into the output list." .
+
+list:firstRest a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Pairs/unpairs a list with (first rest). Supports constructing open lists in some cases." .
+
+# --- log: ------------------------------------------------------------
+
+log:equalTo a ex:Builtin ; ex:kind ex:Relation ;
+  rdfs:comment "Unification: succeeds iff subject and object unify; may bind variables." .
+
+log:notEqualTo a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Constraint/test: succeeds iff subject and object do NOT unify (implemented as: if unification succeeds, builtin fails). No new bindings returned." .
+
+log:conjunction a ex:Builtin ; ex:kind ex:Meta ;
+  rdfs:comment "Merges a list of formulas into one formula; removes duplicate triples; accepts 'true' as empty formula." .
+
+log:conclusion a ex:Builtin ; ex:kind ex:Meta ;
+  rdfs:comment "Computes deductive closure of a formula (including rule inferences) and unifies/binds object with that formula." .
+
+log:content a ex:Builtin ; ex:kind ex:IO ;
+  rdfs:comment "Dereferences subject IRI (fragment-stripped) and returns retrieved bytes as xsd:string." .
+
+log:semantics a ex:Builtin ; ex:kind ex:IO ;
+  rdfs:comment "Dereferences and parses subject IRI as N3/Turtle into a formula." .
+
+log:semanticsOrError a ex:Builtin ; ex:kind ex:IO ;
+  rdfs:comment "Like log:semantics, but returns an xsd:string error message term when dereference/parse fails." .
+
+log:parsedAsN3 a ex:Builtin ; ex:kind ex:Meta ;
+  rdfs:comment "Parses an N3 string (xsd:string-ish) into a formula." .
+
+log:rawType a ex:Builtin ; ex:kind ex:Meta ;
+  rdfs:comment "Returns one of log:Formula, log:Literal, rdf:List, or log:Other for the subject term." .
+
+log:dtlit a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Builds a datatype literal from (lex datatypeIri). Binds/unifies object with the resulting Literal." .
+
+log:langlit a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Builds a language-tagged literal from (lex lang). Binds/unifies object with the resulting Literal." .
+
+log:implies a ex:Builtin ; ex:kind ex:Relation ;
+  rdfs:comment "Rule/formula relation used for =>. In superRestrictedMode, this and log:impliedBy are the only builtins treated as builtins." .
+
+log:impliedBy a ex:Builtin ; ex:kind ex:Relation ;
+  rdfs:comment "Rule/formula relation used for <=." .
+
+log:includes a ex:Builtin ; ex:kind ex:Generator ;
+  rdfs:comment "Proves the object formula in the (possibly scoped) facts/rules; returns the set of proof substitutions (may bind variables)." .
+
+log:notIncludes a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Constraint/test: succeeds iff proving the object formula yields no solutions. No new bindings." .
+
+log:collectAllIn a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Scoped collector: given (valueTemplate whereClause outList) and a scope formula, collects all solutions of whereClause and binds/unifies outList with the list of instantiated valueTemplate results." .
+
+log:forAllIn a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Constraint/test: for all solutions of whereClause, thenClause must have at least one solution in the same scope. No new bindings." .
+
+log:skolem a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Deterministically maps a ground subject term to a Skolem IRI under https://eyereasoner.github.io/.well-known/genid/ and binds/unifies object to it." .
+
+log:uri a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Converts between an IRI and its string representation (with safety checks on IRIREF characters)." .
+
+log:trace a ex:Builtin ; ex:kind ex:SideEffect ;
+  rdfs:comment "Side-effect (debug tracing). Prints '<subject> TRACE <object>' to stderr (Node: process.stderr; browser: console.error). Always succeeds once; does not bind variables.
+
+log:outputString a ex:Builtin ; ex:kind ex:SideEffect ;
+  rdfs:comment "Side-effect (printing). Requires ground subject and non-variable object string. Does not bind variables.
+
+# --- string: (tests + functions) ------------------------------------
+
+string:concatenation a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Concatenates a list of string-ish terms; binds/unifies object with the resulting string literal." .
+
+string:contains a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Constraint/test: subject contains object (substring). No bindings." .
+
+string:containsIgnoringCase a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Constraint/test: case-insensitive contains. No bindings." .
+
+string:endsWith a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Constraint/test: subject ends with object. No bindings." .
+
+string:startsWith a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Constraint/test: subject starts with object. No bindings." .
+
+string:equalIgnoringCase a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Constraint/test: case-insensitive equality. No bindings." .
+
+string:notEqualIgnoringCase a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Constraint/test: case-insensitive inequality. No bindings." .
+
+string:greaterThan a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Constraint/test: Unicode codepoint order (>) on decoded strings. No bindings." .
+
+string:lessThan a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Constraint/test: Unicode codepoint order (<) on decoded strings. No bindings." .
+
+string:notGreaterThan a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Constraint/test: Unicode codepoint order (<=). No bindings." .
+
+string:notLessThan a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Constraint/test: Unicode codepoint order (>=). No bindings." .
+
+string:matches a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Constraint/test: regex match. Pattern is compiled with swap-style escaping helper. No bindings." .
+
+string:notMatches a ex:Builtin ; ex:kind ex:Test ; ex:isConstraint true ;
+  rdfs:comment "Constraint/test: negated regex match. No bindings." .
+
+string:replace a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Regex replace: subject list (data pattern replacement) -> output string literal." .
+
+string:scrape a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Regex scrape: subject list (data pattern) -> first capturing group (as string literal) if match succeeds." .
+
+string:format a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Simple formatter: (fmt arg1 ... argN) -> output string. Only %s and %% are supported; other specifiers fail." .
+
+string:jsonPointer a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "JSON Pointer lookup: (jsonText pointer) -> value term. Expects rdf:JSON-typed literal (or treated as rdf:JSON); caches parsed JSON and pointer lookups." .

package/eyeling.js

@@ -400,6 +400,27 @@ let proofCommentsEnabled = false;
 // Super restricted mode: disable *all* builtins except => / <= (log:implies / log:impliedBy)
 let superRestrictedMode = false;
 
+// Debug/trace printing support (log:trace)
+let __tracePrefixes = null;
+
+function __traceWriteLine(line) {
+  // Prefer stderr in Node, fall back to console.error elsewhere.
+  try {
+    if (
+      __IS_NODE &&
+      typeof process !== 'undefined' &&
+      process.stderr &&
+      typeof process.stderr.write === 'function'
+    ) {
+      process.stderr.write(String(line) + '\n');
+      return;
+    }
+  } catch (_) {}
+  try {
+    if (typeof console !== 'undefined' && typeof console.error === 'function') console.error(line);
+  } catch (_) {}
+}
+
 // ----------------------------------------------------------------------------
 // Deterministic time support
 // ----------------------------------------------------------------------------
@@ -4131,7 +4152,7 @@ function evalCryptoHashBuiltin(g, subst, algo) {
 // ===========================================================================
 // Backward proof & builtins mutual recursion — declarations first
 
-function evalBuiltin(goal, subst, facts, backRules, depth, varGen) {
+function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
   const g = applySubstTriple(goal, subst);
   const pv = iriValue(g.p);
   if (pv === null) return null;
@@ -5648,7 +5669,7 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen) {
 
     const visited2 = [];
     // Start from the incoming substitution so bindings flow outward.
-    return proveGoals(Array.from(g.o.triples), { ...subst }, scopeFacts, [], depth + 1, visited2, varGen);
+    return proveGoals(Array.from(g.o.triples), { ...subst }, scopeFacts, [], depth + 1, visited2, varGen, maxResults);
   }
 
   // log:notIncludes
@@ -5669,10 +5690,25 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen) {
     });
 
     const visited2 = [];
-    const sols = proveGoals(Array.from(g.o.triples), { ...subst }, scopeFacts, [], depth + 1, visited2, varGen);
+    const sols = proveGoals(Array.from(g.o.triples), { ...subst }, scopeFacts, [], depth + 1, visited2, varGen, 1);
     return sols.length ? [] : [{ ...subst }];
   }
 
+  // log:trace
+  // Schema: $s? log:trace $o?
+  // Side-effecting debug output (to stderr). Always succeeds once.
+  // to mimic EYE's fm(...) formatting branch.
+  if (pv === LOG_NS + 'trace') {
+    const pref = __tracePrefixes || PrefixEnv.newDefault();
+    const xStr = termToN3(g.s, pref);
+
+    const xNum = parseNum(g.s);
+    const yStr = termToN3(g.o, pref);
+
+    __traceWriteLine(`${xStr} TRACE ${yStr}`);
+    return [{ ...subst }];
+  }
+
   // log:outputString
   // Schema: $s+ log:outputString $o+
   // Side-effecting output directive. As a builtin goal, we simply succeed
@@ -6244,10 +6280,11 @@ function maybeCompactSubst(subst, goals, answerVars, depth) {
   return gcCompactForGoals(subst, goals, answerVars);
 }
 
-function proveGoals(goals, subst, facts, backRules, depth, visited, varGen) {
+function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxResults) {
   // Iterative DFS over proof states using an explicit stack.
   // Each state carries its own substitution and remaining goals.
   const results = [];
+  const max = typeof maxResults === 'number' && maxResults > 0 ? maxResults : Infinity;
 
   const initialGoals = Array.isArray(goals) ? goals.slice() : [];
   const initialSubst = subst ? { ...subst } : {};
@@ -6258,6 +6295,8 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen) {
   gcCollectVarsInGoals(initialGoals, answerVars);
   if (!initialGoals.length) {
     results.push(gcCompactForGoals(initialSubst, [], answerVars));
+
+    if (results.length >= max) return results;
     return results;
   }
 
@@ -6275,6 +6314,8 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen) {
 
     if (!state.goals.length) {
       results.push(gcCompactForGoals(state.subst, [], answerVars));
+
+      if (results.length >= max) return results;
       continue;
     }
 
@@ -6284,13 +6325,18 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen) {
 
     // 1) Builtins
     if (isBuiltinPred(goal0.p)) {
-      const deltas = evalBuiltin(goal0, {}, facts, backRules, state.depth, varGen);
+      const remaining = max - results.length;
+      if (remaining <= 0) return results;
+      const builtinMax = Number.isFinite(remaining) && !restGoals.length ? remaining : undefined;
+      const deltas = evalBuiltin(goal0, {}, facts, backRules, state.depth, varGen, builtinMax);
       const nextStates = [];
       for (const delta of deltas) {
         const composed = composeSubst(state.subst, delta);
         if (composed === null) continue;
         if (!restGoals.length) {
           results.push(gcCompactForGoals(composed, [], answerVars));
+
+          if (results.length >= max) return results;
         } else {
           const nextSubst = maybeCompactSubst(composed, restGoals, answerVars, state.depth + 1);
           nextStates.push({
@@ -6321,6 +6367,8 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen) {
         if (composed === null) continue;
         if (!restGoals.length) {
           results.push(gcCompactForGoals(composed, [], answerVars));
+
+          if (results.length >= max) return results;
         } else {
           const nextSubst = maybeCompactSubst(composed, restGoals, answerVars, state.depth + 1);
           nextStates.push({
@@ -6342,6 +6390,8 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen) {
         if (composed === null) continue;
         if (!restGoals.length) {
           results.push(gcCompactForGoals(composed, [], answerVars));
+
+          if (results.length >= max) return results;
         } else {
           const nextSubst = maybeCompactSubst(composed, restGoals, answerVars, state.depth + 1);
           nextStates.push({
@@ -6454,7 +6504,38 @@ function forwardChain(facts, forwardRules, backRules, onDerived /* optional */)
         const r = forwardRules[i];
         const empty = {};
         const visited = [];
-        const sols = proveGoals(r.premise.slice(), empty, facts, backRules, 0, visited, varGen);
+        // Optimization: if the rule head is **structurally ground** (no vars anywhere, even inside
+        // quoted formulas) and has no head blanks, then the head does not depend on which body
+        // solution we pick. In that case, we only need *one* proof of the body, and once all head
+        // triples are already known we can skip proving the body entirely.
+        function isStrictGroundTerm(t) {
+          if (t instanceof Var) return false;
+          if (t instanceof Blank) return false;
+          if (t instanceof OpenListTerm) return false;
+          if (t instanceof ListTerm) return t.elems.every(isStrictGroundTerm);
+          if (t instanceof GraphTerm) return t.triples.every(isStrictGroundTriple);
+          return true; // Iri/Literal and any other atomic terms
+        }
+        function isStrictGroundTriple(tr) {
+          return isStrictGroundTerm(tr.s) && isStrictGroundTerm(tr.p) && isStrictGroundTerm(tr.o);
+        }
+
+        const headIsStrictGround =
+          !r.isFuse && (!r.headBlankLabels || r.headBlankLabels.size === 0) && r.conclusion.every(isStrictGroundTriple);
+
+        if (headIsStrictGround) {
+          let allKnown = true;
+          for (const tr of r.conclusion) {
+            if (!hasFactIndexed(facts, tr)) {
+              allKnown = false;
+              break;
+            }
+          }
+          if (allKnown) continue;
+        }
+
+        const maxSols = (r.isFuse || headIsStrictGround) ? 1 : undefined;
+        const sols = proveGoals(r.premise.slice(), empty, facts, backRules, 0, visited, varGen, maxSols);
 
         // Inference fuse
         if (r.isFuse && sols.length) {
@@ -6921,6 +7002,8 @@ function reasonStream(n3Text, opts = {}) {
 
   let prefixes, triples, frules, brules;
   [prefixes, triples, frules, brules] = parser.parseDocument();
+  // Make the parsed prefixes available to log:trace output
+  __tracePrefixes = prefixes;
 
   materializeRdfLists(triples, frules, brules);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.7.14",
+  "version": "1.7.16",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [
@@ -20,6 +20,7 @@
   "files": [
     "index.js",
     "eyeling.js",
+    "eyeling-builtins.ttl",
     "test",
     "examples",
     "README.md",