eyeling 1.12.2 → 1.12.4

package/HANDBOOK.md

@@ -26,6 +26,7 @@
 - [Chapter 16 — Extending Eyeling (without breaking it)](#ch16)
 - [Epilogue](#epilogue)
 - [Appendix A — Eyeling user notes](#app-a)
+- [Appendix B — Notation 3: when facts can carry their own logic](#app-b)
 
 ---
 
@@ -123,7 +124,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).
@@ -503,10 +504,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
 
@@ -538,9 +539,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
 
@@ -565,7 +572,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.
 
 ---
 
@@ -871,7 +878,8 @@ These are “function-like” relations where the subject is usually a list and
 
 **Shape:** `( $x1 $x2 ... ) math:sum $total`
 
-- Subject must be a list of **at least two** numeric terms.
+- Subject must be a list of numeric terms (the list may be empty or a singleton).
+- Empty list sums to **0**.
 - Computes the numeric sum.
 - Chooses an output datatype based on the “widest” numeric datatype seen among inputs and (optionally) the object position; integers stay integers unless the result is non-integer.
 
@@ -879,7 +887,9 @@ These are “function-like” relations where the subject is usually a list and
 
 **Shape:** `( $x1 $x2 ... ) math:product $total`
 
-- Same conventions as `math:sum`, but multiplies.
+- Subject must be a list of numeric terms (the list may be empty or a singleton).
+- Empty list product is **1**.
+- Same datatype conventions as `math:sum`, but multiplies.
 
 #### `math:difference`
 
@@ -1910,3 +1920,31 @@ Logic & reasoning background (Wikipedia):
 - [https://en.wikipedia.org/wiki/Prolog](https://en.wikipedia.org/wiki/Prolog)
 - [https://en.wikipedia.org/wiki/Datalog](https://en.wikipedia.org/wiki/Datalog)
 - [https://en.wikipedia.org/wiki/Skolem_normal_form](https://en.wikipedia.org/wiki/Skolem_normal_form)
+
+---
+
+<a id="app-b"></a>
+
+## Appendix B — Notation 3: when facts can carry their own logic
+
+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.
+
+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 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).
+
+Testing is where rule languages either converge or fragment. Different implementations can drift on scoping, blank nodes, quantification, and built-in behavior. N3’s recent direction has been toward explicit, testable semantics, documented separately as model-theoretic foundations: [https://w3c.github.io/N3/reports/20230703/semantics.html](https://w3c.github.io/N3/reports/20230703/semantics.html).
+
+In that context, public conformance suites become more than scoreboards: they are the mechanism by which interoperability becomes measurable. The community test suite lives at [https://codeberg.org/phochste/notation3tests/](https://codeberg.org/phochste/notation3tests/), with comparative results published in its report: [https://codeberg.org/phochste/notation3tests/src/branch/main/reports/report.md](https://codeberg.org/phochste/notation3tests/src/branch/main/reports/report.md).
+
+The comparison with older tools is historically instructive. Cwm (Closed World Machine) was an early, influential RDF data processor and forward-chaining reasoner—part of the lineage that treated RDF (often written in N3) as something executable: [https://www.w3.org/2000/10/swap/doc/cwm](https://www.w3.org/2000/10/swap/doc/cwm).
+
+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.

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 .
 } .