eyeling 1.12.3 → 1.12.5

package/HANDBOOK.md

@@ -27,6 +27,7 @@
 - [Epilogue](#epilogue)
 - [Appendix A — Eyeling user notes](#app-a)
 - [Appendix B — Notation 3: when facts can carry their own logic](#app-b)
+- [Appendix C — N3 beyond Prolog: logic that survives the open web](#app-c)
 
 ---
 
@@ -124,7 +125,7 @@ If you want to follow the code in the same order Eyeling “thinks”, read:
    - deterministic Skolem IDs (head existentials + `log:skolem`) (`lib/skolem.js`)
 6. `lib/builtins.js` — builtin predicate evaluation plus shared literal/number/string/list helpers:
    - `makeBuiltins(deps)` dependency-injects engine hooks (unification, proving, deref, …)
-   - exports `evalBuiltin(...)` and `isBuiltinPred(...)` back to the engine
+   - and returns `{ evalBuiltin, isBuiltinPred }` back to the engine
    - includes `materializeRdfLists(...)`, a small pre-pass that rewrites _anonymous_ `rdf:first`/`rdf:rest` linked lists into concrete N3 list terms so `list:*` builtins can work uniformly
 7. `lib/explain.js` — proof comments + `log:outputString` aggregation (fact ordering and pretty output).
 8. `lib/deref.js` — synchronous dereferencing for `log:content` / `log:semantics` (used by builtins and engine).
@@ -504,10 +505,10 @@ At each step:
    - apply the current substitution to it
    - attempt to satisfy it in three ways:
      1. built-ins
-     2. facts
-     3. backward rules
+     2. backward rules
+     3. facts
 
-Eyeling’s order is intentional: built-ins often bind variables cheaply; rules expand search trees.
+Eyeling’s order is intentional: built-ins often bind variables cheaply; backward rules expand the search tree (and enable recursion); facts are tried last as cheap terminal matches.
 
 ### 8.3 Built-ins: return _deltas_, not full substitutions
 
@@ -539,9 +540,15 @@ Conjunction in N3 is order-insensitive, but many builtins are only useful once s
 
 That second case matters for “satisfiable but non-enumerating” builtins (e.g., some `log:` helpers) where early vacuous success would otherwise prevent later goals from ever binding the variables the builtin needs.
 
-### 8.4 Loop prevention: a simple visited list
+### 8.4 Loop prevention: visited multiset with backtracking
 
-Eyeling prevents obvious infinite recursion by skipping a goal if it is already in the `visited` list. This is a pragmatic check; it doesn’t implement full tabling, but it avoids the most common “A depends on A” loops.
+Eyeling avoids obvious infinite recursion by recording each (substituted) goal it is currently trying in a per-branch _visited_ structure. If the same goal is encountered again on the same proof branch, Eyeling skips it.
+
+Implementation notes:
+
+- The visited structure is a `Map` from _goal key_ to a reference count, plus a trail array. This makes it cheap to check (`O(1)` average) and cheap to roll back on backtracking (just like the substitution trail).
+- Keys are _structural_. Atoms use stable IDs; lists use element keys; variables use their identity (so two different variables are **not** conflated). This keeps the cycle check conservative and avoids accidental pruning.
+- This is not full tabling: it does not memoize answers, it only guards against immediate cycles (the common “A depends on A” loops).
 
 ### 8.5 Backward rules: indexed by head predicate
 
@@ -566,7 +573,7 @@ To reduce allocation pressure, Eyeling reuses a single fresh `Var(...)` object p
 The trail-based substitution store removes the biggest accidental quadratic cost (copying a growing substitution object at every step).  
 In deep and branchy searches, the substitution trail still grows, and long variable-to-variable chains increase the work done by `applySubstTerm`.
 
-Eyeling currently keeps the full trail as-is during search and when emitting answers; it does not run a substitution compaction pass, and it does not perform explicit substitution composition.
+Eyeling currently keeps the full trail as-is during search. When emitting a solution, it runs a lightweight compaction pass (via `gcCollectVarsInGoals(...)` / `gcCompactForGoals(...)`) so only bindings reachable from the answer variables and remaining goals are kept. It still does not perform general substitution composition/normalization during search.
 
 ---
 
@@ -1923,13 +1930,13 @@ Logic & reasoning background (Wikipedia):
 
 RDF succeeded by making a radical constraint feel natural: reduce meaning to small, uniform statements—triples—that can be published, merged, and queried across boundaries. A triple does not presume a database schema, a programming language, or a particular application. It presumes only that names (IRIs) can be shared, and that graphs can be combined.
 
-That strength also marks RDF’s limit. The moment a graph is expected to *do* something—normalize values, reconcile vocabularies, derive implied relationships, enforce a policy, compute a small transformation—logic tends to migrate into code. The graph becomes an inert substrate while the decisive semantics hide in scripts, services, ETL pipelines, or bespoke rule engines. What remains portable is the data; what often becomes non-portable is the meaning.
+That strength also marks RDF’s limit. The moment a graph is expected to _do_ something—normalize values, reconcile vocabularies, derive implied relationships, enforce a policy, compute a small transformation—logic tends to migrate into code. The graph becomes an inert substrate while the decisive semantics hide in scripts, services, ETL pipelines, or bespoke rule engines. What remains portable is the data; what often becomes non-portable is the meaning.
 
-Notation 3 (N3) sits precisely at that seam. It remains a readable way to write RDF, but it also treats *graphs themselves* as objects that can be described, matched, and related. The N3 Community Group’s specification presents N3 as an assertion and logic language that extends RDF rather than replacing it: [https://w3c.github.io/N3/spec/](https://w3c.github.io/N3/spec/).
+Notation 3 (N3) sits precisely at that seam. It remains a readable way to write RDF, but it also treats _graphs themselves_ as objects that can be described, matched, and related. The N3 Community Group’s specification presents N3 as an assertion and logic language that extends RDF rather than replacing it: [https://w3c.github.io/N3/spec/](https://w3c.github.io/N3/spec/).
 
 The essential move is quotation: writing a graph inside braces as a thing that can be discussed. Once graphs can be quoted, rules become graph-to-graph transformations. The familiar implication form, `{ … } => { … } .`, reads as a piece of prose: whenever the antecedent pattern holds, the consequent pattern follows. Tim Berners-Lee’s design note frames this as a web-friendly logic with variables and nested graphs: [https://www.w3.org/DesignIssues/Notation3.html](https://www.w3.org/DesignIssues/Notation3.html).
 
-This style of rule-writing is more than syntactic sugar. It keeps the unit of exchange stable. Inputs are RDF graphs; outputs are RDF graphs. Inference produces new triples rather than hidden internal state. Rule sets can be versioned alongside data, reviewed as text, and executed by different engines that implement the same semantics. That portability theme runs back to the original W3C Team Submission: [https://www.w3.org/TeamSubmission/n3/](https://www.w3.org/TeamSubmission/n3/).
+This style of rule-writing makes rules first-class, publishable artifacts. It keeps the unit of exchange stable. Inputs are RDF graphs; outputs are RDF graphs. Inference produces new triples rather than hidden internal state. Rule sets can be versioned alongside data, reviewed as text, and executed by different engines that implement the same semantics. That portability theme runs back to the original W3C Team Submission: [https://www.w3.org/TeamSubmission/n3/](https://www.w3.org/TeamSubmission/n3/).
 
 Practical reasoning also depends on computation: lists, strings, math, comparisons, and the other “small operations” that integration work demands. N3 addresses this by standardizing built-ins—predicates with predefined behavior that can be used inside rule bodies while preserving the declarative, graph-shaped idiom. The built-ins report is here: [https://w3c.github.io/N3/reports/20230703/builtins.html](https://w3c.github.io/N3/reports/20230703/builtins.html).
 
@@ -1941,4 +1948,23 @@ The comparison with older tools is historically instructive. Cwm (Closed World M
 
 What motivates Notation 3, in the end, is architectural restraint. It refuses to let “logic” become merely a private feature of an application stack. It keeps meaning close to the graph: rules are expressed as graph patterns; results are expressed as triples; computation is pulled in through well-defined built-ins rather than arbitrary code. This produces a style of working where integration and inference are not sidecar scripts, but publishable artifacts—documents that can be inspected, shared, tested, and reused.
 
-In that sense, N3 is less a bid to make the web “smarter” than a bid to make meaning *portable*: not only facts that travel, but also the explicit steps by which facts can be connected, extended, and made actionable—without abandoning the simplicity that made triples travel in the first place.
+In that sense, N3 is less a bid to make the web “smarter” than a bid to make meaning _portable_: not only facts that travel, but also the explicit steps by which facts can be connected, extended, and made actionable—without abandoning the simplicity that made triples travel in the first place.
+
+---  
+
+## Appendix C — N3 beyond Prolog: logic that survives the open web
+
+At first glance, an N3 rule set can feel familiar if you’ve used Prolog: variables, unification, and rules that read like “if this pattern holds, then that pattern follows.” But N3 is not just “logic programming with a different syntax.” It is logic shaped for a different environment: not a single program with a single database, but a world of distributed graphs that can be published, merged, and cited across boundaries.
+
+That change of environment forces a change in what “beyond Prolog” even means. It is less about being more powerful in the abstract, and more about being *more portable as meaning* — logic that stays connected when it moves between documents, vocabularies, and authors.
+
+Several design moves push N3 into that web-native space:
+
+- **Global identity is the default.** Names are IRIs. A rule does not merely compute with local symbols; it operates over identifiers meant to be shared across datasets.
+- **Graphs are the unit of exchange.** The input is a graph; the output is a graph. Inference produces new triples rather than hidden internal state, so results can travel the same way the facts do.
+- **Statements can be treated as data.** Quoted graphs let you talk *about* assertions: claims, policies, provenance, “this source says …,” “this formula implies …,” and other meta-level structure that is awkward in a plain predicate database.
+- **Rules can be publishable artifacts.** Rules can live alongside data as text, be versioned, reviewed, and reused — the “meaning” is not forced back into an external codebase.
+- **Web-like computation can be pulled into rule bodies.** Built-ins make room for the small computations that real integration needs (strings, lists, comparisons), and some N3 workflows even treat IRIs as pointers to more knowledge.
+
+In that sense, Prolog is a superb engine for proving things *inside* a chosen world. N3 is a way to write rules so they keep working *across* worlds: across documents, across graph boundaries, and across the open-ended growth of linked data. When an engine like Eyeling solves rule bodies with a Prolog-like prover but still saturates forward consequences, it’s exactly this bridge: Prolog-style execution serving a web-scale, graph-first notion of meaning.
+

package/examples/ackermann.n3

@@ -0,0 +1,89 @@
+# ==================
+# Ackermann function
+# ==================
+#
+# See https://en.wikipedia.org/wiki/Ackermann_function
+
+@prefix math: <http://www.w3.org/2000/10/swap/math#>.
+@prefix log: <http://www.w3.org/2000/10/swap/log#>.
+@prefix : <https://eyereasoner.github.io/ns#>.
+
+# ackermann(x, y)
+{
+    (?X ?Y) :ackermann ?A.
+} <= {
+    (?Y 3) math:sum ?B.
+    (?X ?B 2) :ackermann ?C.
+    (?C 3) math:difference ?A.
+}.
+
+# ackermann(x, y, z)
+# succ (x=0)
+{
+    (0 ?Y ?Z) :ackermann ?A.
+} <= {
+    (?Y 1) math:sum ?A.
+}.
+
+# sum (x=1)
+{
+    (1 ?Y ?Z) :ackermann ?A.
+} <= {
+    (?Y ?Z) math:sum ?A.
+}.
+
+# product (x=2)
+{
+    (2 ?Y ?Z) :ackermann ?A.
+} <= {
+    (?Y ?Z) math:product ?A.
+}.
+
+# exponentiation (x=3), tetration (x=4), pentation (x=5), hexation (x=6), etc
+{
+    (?X 0 ?Z) :ackermann 1.
+} <= {
+    ?X math:greaterThan 2.
+}.
+
+{
+    (?X ?Y ?Z) :ackermann ?A.
+} <= {
+    ?X math:greaterThan 2.
+    ?Y math:notEqualTo 0.
+    (?Y 1) math:difference ?B.
+    (?X ?B ?Z) :ackermann ?C.
+    (?X 1) math:difference ?D.
+    (?D ?C ?Z) :ackermann ?A.
+}.
+
+# test
+{
+    (0 0) :ackermann ?A0.
+    (0 6) :ackermann ?A1.
+    (1 2) :ackermann ?A2.
+    (1 7) :ackermann ?A3.
+    (2 2) :ackermann ?A4.
+    (2 9) :ackermann ?A5.
+    (3 4) :ackermann ?A6.
+    (3 1000) :ackermann ?A7.
+    (4 0) :ackermann ?A8.
+    (4 1) :ackermann ?A9.
+    #(4 2) :ackermann ?A10.
+    (5 0) :ackermann ?A11.
+} => {
+    :test :is {
+        (0 0) :ackermann ?A0.
+        (0 6) :ackermann ?A1.
+        (1 2) :ackermann ?A2.
+        (1 7) :ackermann ?A3.
+        (2 2) :ackermann ?A4.
+        (2 9) :ackermann ?A5.
+        (3 4) :ackermann ?A6.
+        (3 1000) :ackermann ?A7.
+        (4 0) :ackermann ?A8.
+        (4 1) :ackermann ?A9.
+        #(4 2) :ackermann ?A10.
+        (5 0) :ackermann ?A11.
+    }.
+}.

package/examples/fibonacci.n3

@@ -22,12 +22,14 @@
     1 :fibonacci ?F1.
     10 :fibonacci ?F10.
     100 :fibonacci ?F100.
+    1000 :fibonacci ?F1000.
 } => {
     :test :is {
         0 :fibonacci ?F0.
         1 :fibonacci ?F1.
         10 :fibonacci ?F10.
         100 :fibonacci ?F100.
+        1000 :fibonacci ?F1000.
     }.
 }.
 

package/examples/output/ackermann.n3

@@ -0,0 +1,15 @@
+@prefix : <https://eyereasoner.github.io/ns#> .
+
+:test :is {
+    (0 0) :ackermann 1 .
+    (0 6) :ackermann 7 .
+    (1 2) :ackermann 4 .
+    (1 7) :ackermann 9 .
+    (2 2) :ackermann 7 .
+    (2 9) :ackermann 21 .
+    (3 4) :ackermann 125 .
+    (3 1000) :ackermann 85720688574901385675874003924800144844912384936442688595500031069628084089994889799455870305255668650207573833404251746014971622855385123487876620597588598431476542198593847883368596840498969135023633457224371799868655530139190140473324351568616503316569571821492337341283438653220995094697645344555005 .
+    (4 0) :ackermann 13 .
+    (4 1) :ackermann 65533 .
+    (5 0) :ackermann 65533 .
+} .

package/examples/output/fibonacci.n3

@@ -5,4 +5,5 @@
     1 :fibonacci 1 .
     10 :fibonacci 55 .
     100 :fibonacci 354224848179261915075 .
+    1000 :fibonacci 43466557686937456435688527675040625802564660517371780402481729089536555417949051890403879840079255169295922593080322634775209689623239873322471161642996440906533187938298969649928516003704476137795166849228875 .
 } .

package/examples/output/patch.n3

@@ -0,0 +1,10 @@
+@prefix : <http://example.org/> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+
+:patch1 :result {
+    :alice a :Person .
+    :bob a :Person .
+    :alice :age 31 .
+    :alice :status :ActiveStatus .
+    :alice :verified true .
+} .

package/examples/patch.n3

@@ -0,0 +1,55 @@
+# ===================================================================
+# N3 graph patch example
+# - Removes every triple from :source that is also present in :delete
+# - Then adds all triples from :insert
+# Uses only N3 builtins from the W3C spec:
+#   log:collectAllIn, log:conjunction, log:notIncludes
+# ===================================================================
+
+@prefix :    <http://example.org/> .
+@prefix log: <http://www.w3.org/2000/10/swap/log#> .
+
+:patch1
+  :source {
+    :alice a :Person ;
+           :age 30 ;
+           :status :OldStatus ;
+           :email "alice@example.org" .
+    :bob   a :Person .
+  } ;
+  :delete {
+    :alice :age 30 ;
+           :status :OldStatus ;
+           :email "alice@example.org" .
+  } ;
+  :insert {
+    :alice :age 31 ;
+           :status :ActiveStatus ;
+           :verified true .
+  } .
+
+{
+  :patch1 :source ?G ;
+          :delete ?Del ;
+          :insert ?Ins .
+
+  # Collect exactly the triples from ?G that are NOT included in the delete graph term ?Del
+  ( { ?S ?P ?O . }
+    {
+      ?S ?P ?O .
+      ?Del log:notIncludes { ?S ?P ?O . } .
+    }
+    ?keptTriples
+  ) log:collectAllIn ?G .
+
+  # Merge kept graph terms back into a single graph term
+  ?keptTriples log:conjunction ?keptGraph .
+
+  # Add the insert graph term
+  ( ?keptGraph ?Ins ) log:conjunction ?patched .
+}
+=>
+{
+  :patch1 :result ?patched .
+} .
+