eyeling 1.11.15 → 1.11.17

package/HANDBOOK.md

@@ -553,21 +553,12 @@ That “standardize apart” step is essential. Without it, reusing a rule multi
 **Implementation note (performance):** `standardizeRule` is called for every backward-rule candidate during proof search.  
 To reduce allocation pressure, Eyeling reuses a single fresh `Var(...)` object per *original* variable name within one standardization pass (all occurrences of `?x` in the rule become the same fresh `?x__N` object). This is semantics-preserving — it still “separates” invocations — but it avoids creating many duplicate Var objects when a variable appears repeatedly in a rule body.
 
-### 8.6 Substitution compaction: keeping DFS fast on deep proofs
+### 8.6 Substitution size on deep proofs
 
 The trail-based substitution store removes the biggest accidental quadratic cost (copying a growing substitution object at every step).  
-But substitutions can still grow large in deep/branchy searches, and long variable chains make `applySubstTerm` work harder.
+In deep and branchy searches, the substitution trail still grows, and long variable-to-variable chains increase the work done by `applySubstTerm`.
 
-Eyeling therefore still uses `maybeCompactSubst` when emitting answers (and occasionally during deep search): it keeps only bindings relevant to the remaining goals and the original “answer variables”, trimming dead bindings and shortening chains.
-
-
-* if depth is high or substitution is large, it keeps only bindings relevant to:
-
-  * the remaining goals
-  * variables from the original goal list (“answer variables”)
-  * plus variables transitively referenced inside kept bindings
-
-This is semantics-preserving for the ongoing proof search, but dramatically improves performance on deep recursive proofs.
+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.
 
 ---
 

package/README.md

@@ -10,6 +10,7 @@ A compact [Notation3 (N3)](https://notation3.org/) reasoner in **JavaScript**.
 ## Links
 
 - **Handbook:** [https://eyereasoner.github.io/eyeling/HANDBOOK](https://eyereasoner.github.io/eyeling/HANDBOOK)
+- **Semantics:** [https://eyereasoner.github.io/eyeling/SEMANTICS](https://eyereasoner.github.io/eyeling/SEMANTICS)
 - **Playground:** [https://eyereasoner.github.io/eyeling/demo](https://eyereasoner.github.io/eyeling/demo)
 - **Notation3 test suite:** [https://codeberg.org/phochste/notation3tests](https://codeberg.org/phochste/notation3tests)
 - **Eyeling conformance report:** [https://codeberg.org/phochste/notation3tests/src/branch/main/reports/report.md](https://codeberg.org/phochste/notation3tests/src/branch/main/reports/report.md)

package/SEMANTICS.md

@@ -0,0 +1,56 @@
+How does the [Eyeling HANDBOOK](https://eyereasoner.github.io/eyeling/HANDBOOK) line up with the W3C CG [Notation3 Semantics](https://w3c.github.io/N3/spec/semantics) document — and where does it intentionally diverge?
+
+## Where Eyeling is strongly aligned
+
+* **Core term model (IRIs, literals, variables, blank nodes, lists, quoted formulas):**
+  The semantics spec treats N3 terms as IRIs/literals/variables plus **lists** and **graph terms**.
+  Eyeling’s handbook describes the same internal term universe: `Iri`, `Literal`, `Var`, `Blank`, `ListTerm`, `GraphTerm`.
+
+* **Quoted formulas need alpha-equivalence / isomorphism:**
+  The semantics spec defines isomorphism for graphs and graph terms using renaming mappings (including special handling for nested scopes).
+  Eyeling implements this operationally as **alpha-equivalence for `GraphTerm`**, explicitly describing “consistent renaming” as the match criterion.
+
+* **Rules as implication (and `true` as empty formula):**
+  The semantics spec defines log-semantics for `log:implies` and explicitly treats boolean `true`/`false` as special literals, with `true` corresponding to the empty formula.
+  Eyeling’s parser/normalizer explicitly supports `{P} => {C}` and `{P} log:implies {C}`, and treats `true` as `{}`.
+
+* **Lists as first-class citizens (not just RDF collections):**
+  The semantics spec treats lists as proper N3 terms.
+  Eyeling uses concrete `ListTerm`s and even materializes RDF `rdf:first`/`rdf:rest` chains into list terms to operate uniformly.
+
+## Where Eyeling diverges or goes beyond the semantics doc
+
+### 1) Blank nodes in **rule bodies**: Eyeling chooses “N3 practice” over “bnodes are existential”
+
+The semantics doc states (for concrete syntax intuition) that **blank nodes correspond to existentially quantified variables** with **local scope**.
+Eyeling *intentionally* rewrites blanks in **premises** into variables (“universally-quantified placeholders”), to avoid “existential in the body” behavior.
+
+This is a *real semantic choice*: it matches how many people *write* N3 rules, but it is not the same as a straightforward “bnodes are existentials everywhere” reading.
+
+### 2) “Groundness” of quoted formulas containing variables
+
+In the semantics spec, whether a graph term is ground depends on whether the underlying graph is closed (no free variables), and it discusses how variables can appear free when you isolate a nested graph term.
+Eyeling explicitly makes a pragmatic choice: **variables inside a `GraphTerm` do not make the surrounding triple non-ground** (“variables inside formulas don’t leak”).
+
+That’s convenient for operational indexing/matching, but it doesn’t mirror the model-theoretic notion of ground graph terms one-to-one.
+
+### 3) Eyeling implements lots of behavior the semantics doc does not yet define
+
+The semantics report currently only gives special meaning to `log:implies` (and says LP is planned to be extended).
+Eyeling defines a large operational “standard library” of builtins and advanced control features (e.g., scoped querying / snapshotting). For example, it gives `log:includes`/`log:notIncludes` a two-phase snapshot semantics for determinism.
+
+So: Eyeling is **ahead of / outside** what `semantics.html` formally specifies today.
+
+### 4) Constraint handling via “inference fuses” (`=> false`) is operational
+
+The semantics doc includes a notion of `false` in connection with `log:implies` constraints.
+Eyeling turns `{...} => false` into an *engine-level hard failure* (exit status, message), i.e., a procedural constraint mechanism rather than just a semantic condition.
+
+That’s useful in tooling, but it’s not something the model-theoretic semantics itself “does” (it defines truth/entailment, not process control).
+
+### 5) Possible coverage gaps vs full N3 surface language (not strictly “semantics.html”, but relevant)
+
+Eyeling’s handbook lists supported directives/tokens (`@prefix`, `@base`, etc.) but does not mention explicit quantifier directives like `@forAll` / `@forSome`.
+The semantics document leans on explicit quantification in its **abstract syntax** discussion.
+So Eyeling appears to support *implicit* quantification via `?x` and blanks (plus its own rule-normalization choices), but may not implement the full explicit-quantifier surface syntax.
+

package/examples/godel-template.n3

@@ -0,0 +1,172 @@
+# ============================================================================
+# Gödel Template + Substitution Example
+#
+# Goal
+#   Model a “Gödel-like” sentence as DATA:
+#     - a token template with a hole (prefix ++ numeral(n) ++ suffix)
+#     - a substitution step that splices in the decimal numeral tokens for n
+#     - a Gödel encoding that maps the resulting token list to a number:
+#         g = Π prime[i] ^ code(token[i])
+#
+# Notes
+#   • This is a toy arithmetization: the token alphabet and codes are small and
+#     illustrative, not the full formal encoding used in incompleteness proofs.
+#   • The numeral construction is demand-driven via backward rules (<=):
+#     Eyeling will only compute digits(n) when some other rule needs it.
+#   • Integer quotient is obtained via:
+#       r = n mod 10
+#       q = (n - r) / 10
+#     so q stays integral even though math:quotient is real division.
+#
+# What to look for in the output
+#   - :Demo :digits ( :d4 :d2 )                     (numeral tokens)
+#   - :Demo :tokens ( ... :d4 :d2 ... )             (instantiated sentence)
+#   - :Demo :godelPairs ( (2 c0) (3 c1) ... )       (prime/exponent pairs)
+#   - :Demo :godelNumber <big integer>              (Gödel number)
+# ============================================================================
+
+@prefix :     <http://example.org/godel-template#>.
+@prefix list: <http://www.w3.org/2000/10/swap/list#>.
+@prefix log:  <http://www.w3.org/2000/10/swap/log#>.
+@prefix math: <http://www.w3.org/2000/10/swap/math#>.
+
+# ----------------------------------------------------------------------------
+# 0) Token alphabet + codes (toy)
+# ----------------------------------------------------------------------------
+
+:NOT       :code  1.
+:PROVABLE  :code  2.
+:IN        :code  3.
+:S         :code  4.
+:LP        :code  5.
+:RP        :code  6.
+
+# Digit tokens (each has a numeric value + a token code)
+:d0 :digitValue 0; :code 10.
+:d1 :digitValue 1; :code 11.
+:d2 :digitValue 2; :code 12.
+:d3 :digitValue 3; :code 13.
+:d4 :digitValue 4; :code 14.
+:d5 :digitValue 5; :code 15.
+:d6 :digitValue 6; :code 16.
+:d7 :digitValue 7; :code 17.
+:d8 :digitValue 8; :code 18.
+:d9 :digitValue 9; :code 19.
+
+# primes for positions 0.. (enough for prefix + digits + suffix)
+:primeBases :is ( 2 3 5 7 11 13 17 19 23 29 31 37 41 43 47 53 59 61 67 71 ).
+
+# ----------------------------------------------------------------------------
+# 1) Template schema as data
+#    Think:  NOT PROVABLE IN S ( <decimal numeral> )
+# ----------------------------------------------------------------------------
+
+:GSchema a :Template;
+  :english "This statement cannot be proven within this system.";
+  :prefixTokens ( :NOT :PROVABLE :IN :S :LP );
+  :suffixTokens ( :RP ).
+
+# ----------------------------------------------------------------------------
+# 2) Decimal numeral tokens via backward rules (demand-driven)
+# ----------------------------------------------------------------------------
+
+# Base case: n < 10  => digits(n) = ( d(n) )
+{
+  ?n :digits ( ?d ).
+} <= {
+  ?n math:lessThan 10.
+  ?d :digitValue ?n.
+}.
+
+# Recursive case: n >= 10
+# digits(n) = digits(q) ++ ( d(r) )
+#   where r = n mod 10
+#         q = (n - r)/10  (integer-safe)
+{
+  ?n :digits ?digs.
+} <= {
+  ?n math:notLessThan 10.
+
+  ( ?n 10 ) math:remainder ?r.
+  ( ?n ?r ) math:difference ?nMinusR.
+  ( ?nMinusR 10 ) math:quotient ?q.
+
+  ?q :digits ?qdigs.
+  ?dr :digitValue ?r.
+
+  ( ?qdigs ( ?dr ) ) list:append ?digs.
+}.
+
+# ----------------------------------------------------------------------------
+# 3) Substitute numeral(n) into the template to get the token list
+# ----------------------------------------------------------------------------
+
+:Demo :n 42.
+
+{
+  :Demo :n ?n.
+  ?n :digits ?digits.
+
+  :GSchema :prefixTokens ?pre.
+  :GSchema :suffixTokens ?suf.
+
+  ( ?pre ?digits ) list:append ?tmp.
+  ( ?tmp ?suf ) list:append ?tokens.
+}
+=>
+{
+  :Demo :digits ?digits.
+  :Demo :tokens ?tokens.
+}.
+
+# ----------------------------------------------------------------------------
+# 4) Gödel encode tokens: g = Π prime[i] ^ code(token[i])
+#    - build pairs (prime code)
+#    - compute factors prime^code
+#    - multiply factors
+# ----------------------------------------------------------------------------
+
+# Build godelPairs as a list of list-pairs: ( (p0 c0) (p1 c1) ... )
+{
+  :Demo :tokens ?tokens.
+  :primeBases :is ?primes.
+
+  ( (?p ?c)
+    {
+      ?tokens list:iterate (?i ?tok).
+      ( ?primes ?i ) list:memberAt ?p.
+      ?tok :code ?c.
+    }
+    ?pairs
+  ) log:collectAllIn _:scope.
+}
+=>
+{
+  :Demo :godelPairs ?pairs.
+}.
+
+# Compute godelNumber from the factors (p^c) and their product
+{
+  :Demo :godelPairs ?pairs.
+
+  ( ?factor
+    {
+      ?pairs list:member ?pair.
+      ?pair math:exponentiation ?factor.
+    }
+    ?factors
+  ) log:collectAllIn _:scope.
+
+  ?factors math:product ?g.
+}
+=>
+{
+  :Demo :godelNumber ?g.
+
+  # convenient outputs (so you can spot them quickly)
+  :outDigits :is ?digits.
+  :outTokens :is ?tokens.
+  :outPairs  :is ?pairs.
+  :outG      :is ?g.
+}.
+

package/examples/output/godel-template.n3

@@ -0,0 +1,8 @@
+@prefix : <http://example.org/godel-template#> .
+
+:Demo :digits (:d4 :d2) .
+:Demo :tokens (:NOT :PROVABLE :IN :S :LP :d4 :d2 :RP) .
+:Demo :godelPairs ((2 1) (3 2) (5 3) (7 4) (11 5) (13 14) (17 12) (19 6)) .
+:Demo :godelNumber 93897428453934743498383922339000952994095115872750 .
+:outPairs :is ((2 1) (3 2) (5 3) (7 4) (11 5) (13 14) (17 12) (19 6)) .
+:outG :is 93897428453934743498383922339000952994095115872750 .

package/examples/path-discovery.n3

@@ -96451,7 +96451,7 @@ res:AIRPORT_N nepo:hasOutboundRouteTo res:AIRPORT_N.
     ?route list:firstRest (?from ?newRoute).
 }.
 
-# find routes from Manchester-Boston Regional Airport to Helsinki Vantaa Airport with at most 2 stopovers
+# find routes from Ostend-Bruges International Airport to Václav Havel Airport Prague with at most 2 stopovers
 {
     ?source rdfs:label "Ostend-Bruges International Airport".
     ?destination rdfs:label "Václav Havel Airport Prague".

package/eyeling-builtins.ttl

@@ -275,10 +275,10 @@ 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.
+  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.
+  rdfs:comment "Side-effect (printing). Requires ground subject and non-variable object string. Does not bind variables." .
 
 # --- string: (tests + functions) ------------------------------------