eyeling 1.15.8 → 1.15.10

package/HANDBOOK.md

@@ -376,6 +376,10 @@ That’s alpha-equivalence:
 
 Eyeling implements alpha-equivalence by checking whether there exists a consistent renaming mapping between the two formulas’ variables/blanks that makes the triples match.
 
+Important scope nuance: only blanks/variables that are local to the quoted formula participate in alpha-renaming. If a formula is being matched after an outer substitution has already instantiated part of it, those substituted terms are treated as fixed. In other words, alpha-equivalence may rename formula-local placeholders, but it must not rename names that came from the enclosing match. This prevents a substituted outer blank node from being confused with a local blank node inside the quoted formula.
+
+So `{ _:x :p :o }` obtained by substituting `?A = _:x` into `{ ?A :p :o }` must not alpha-match `{ _:b :p :o }` by renaming `_:x` to `_:b`.
+
 ### 6.2 Groundness: “variables inside formulas don’t leak”
 
 Eyeling makes a deliberate choice about _groundness_:

package/README.md

@@ -1,5 +1,7 @@
 # eyeling
 
+[![npm version](https://img.shields.io/npm/v/eyereasoner.svg)](https://www.npmjs.com/package/eyereasoner) [![DOI](https://zenodo.org/badge/581706557.svg)](https://doi.org/10.5281/zenodo.19068086)
+
 A compact [Notation3 (N3)](https://notation3.org/) reasoner in **JavaScript**.
 
 - Single self-contained bundle (`eyeling.js`), no external runtime dependencies

package/examples/composition-of-injective-functions-is-injective.n3

@@ -0,0 +1,241 @@
+# ==========================================================
+# File: composition-of-injective-functions-is-injective.n3
+#
+# Purpose
+# -------
+# This file expresses a standard pure mathematical fact:
+#
+#   The composition of two injective functions is injective.
+#
+# Core idea
+# ---------
+# We choose a framework with:
+#   - functions represented by an application relation :app
+#   - a notion of injectivity
+#   - a notion of composition
+#
+# Once that framework is fixed, the theorem is forced:
+#
+#   if f and g are injective,
+#   then g ∘ f is injective.
+#
+# This fits the general theme:
+#   the framework is chosen,
+#   but the consequence is not optional.
+#
+# Representation
+# --------------
+#   (?f ?x) :app ?y
+# means:
+#   f(x) = y
+#
+#   ?h :compositeOf (?g ?f)
+# means:
+#   h = g ∘ f
+#
+#   (?x ?y) :sameTerm true
+# records provable sameness as an ordinary derived fact.
+# ==========================================================
+
+@prefix :    <http://examples.org/#>.
+@prefix log: <http://www.w3.org/2000/10/swap/log#>.
+
+# ------------------
+# Carrier membership
+# ------------------
+
+# We use:
+#
+#   ?x :inX true.
+#   ?y :inY true.
+#   ?z :inZ true.
+#
+# for the three sets involved.
+
+# -----------------------------------
+# Basic facts about provable sameness
+# -----------------------------------
+
+# Reflexivity on each carrier
+
+{
+  ?x :inX true.
+}
+=>
+{
+  (?x ?x) :sameTerm true.
+}.
+
+{
+  ?y :inY true.
+}
+=>
+{
+  (?y ?y) :sameTerm true.
+}.
+
+{
+  ?z :inZ true.
+}
+=>
+{
+  (?z ?z) :sameTerm true.
+}.
+
+# Symmetry
+
+{
+  (?a ?b) :sameTerm true.
+}
+=>
+{
+  (?b ?a) :sameTerm true.
+}.
+
+
+# ---------
+# Functions
+# ---------
+
+# Functionality:
+# if the same function sends the same input to two outputs,
+# then those outputs are the same.
+
+{
+  (?f ?x) :app ?u.
+  (?f ?x) :app ?v.
+}
+=>
+{
+  (?u ?v) :sameTerm true.
+}.
+
+# Injectivity:
+# if an injective function sends x and y to the same output,
+# then x and y are the same.
+
+{
+  ?f :injective true.
+  (?f ?x) :app ?u.
+  (?f ?y) :app ?v.
+  (?u ?v) :sameTerm true.
+}
+=>
+{
+  (?x ?y) :sameTerm true.
+}.
+
+
+# -----------
+# Composition
+# -----------
+
+# If h = g ∘ f, and f(x) = y, and g(y) = z,
+# then h(x) = z.
+
+{
+  ?h :compositeOf (?g ?f).
+  (?f ?x) :app ?y.
+  (?g ?y) :app ?z.
+}
+=>
+{
+  (?h ?x) :app ?z.
+}.
+
+
+# -----------
+# The theorem
+# -----------
+#
+# Proof idea:
+#
+#   suppose h = g ∘ f
+#   and h(x), h(y) are equal
+#
+#   then g(f(x)) = g(f(y))
+#   since g is injective:
+#       f(x) = f(y)
+#   since f is injective:
+#       x = y
+#
+# So the composition is injective.
+#
+# In this file we record theorem instances with:
+#
+#   (?h ?x ?y) :sameInputUnderEqualCompositeOutput true
+#
+
+{
+  ?h :compositeOf (?g ?f).
+  ?f :injective true.
+  ?g :injective true.
+
+  (?f ?x) :app ?fx.
+  (?f ?y) :app ?fy.
+
+  (?g ?fx) :app ?u.
+  (?g ?fy) :app ?v.
+
+  (?u ?v) :sameTerm true.
+  (?x ?y) :sameTerm true.
+}
+=>
+{
+  (?h ?x ?y) :sameInputUnderEqualCompositeOutput true.
+}.
+
+
+# -----------------
+# Tiny example data
+# -----------------
+# We declare two injective functions f and g, and their
+# composition h = g ∘ f.
+#
+# The data below says:
+#
+#   f(a) = p
+#   f(b) = q
+#   g(p) = r
+#   g(q) = r
+#
+# Since g is injective, p and q must be the same.
+# Since f is injective, a and b must be the same.
+#
+# So h sends a and b to the same value only because
+# the framework forces a = b.
+
+:a :inX true.
+:b :inX true.
+
+:p :inY true.
+:q :inY true.
+
+:r :inZ true.
+
+:f :injective true.
+:g :injective true.
+
+:h :compositeOf (:g :f).
+
+(:f :a) :app :p.
+(:f :b) :app :q.
+
+(:g :p) :app :r.
+(:g :q) :app :r.
+
+
+# -----
+# Query
+# -----
+# Ask for non-trivial cases where equal composite output forces
+# the inputs to be the same.
+
+{
+  (?h ?x ?y) :sameInputUnderEqualCompositeOutput true.
+  ?x log:notEqualTo ?y.
+}
+log:query
+{
+  :result :sameInputByCompositeInjectivity (?h ?x ?y).
+}.

package/examples/equivalence-classes-overlap-implies-same-class.n3

@@ -0,0 +1,183 @@
+# ===============================================================
+# File: equivalence-classes-overlap-implies-same-class.n3
+#
+# Purpose
+# -------
+# This file expresses a small result about equivalence relations:
+#
+#   If two equivalence classes share an element,
+#   then they are the same class.
+#
+# Core idea
+# ---------
+# We choose a framework with a relation :sim and the axioms:
+#   - reflexive
+#   - symmetric
+#   - transitive
+#
+# That is the creative step: we decide to study relations with
+# exactly these properties.
+#
+# Once that framework is fixed, a consequence follows:
+#
+#   if some element ?z belongs to both [x] and [y],
+#   then [x] and [y] are the same equivalence class.
+#
+# In this file:
+#
+#   ?u :inClassOf ?x
+#
+# means that ?u belongs to the equivalence class of ?x,
+# i.e. ?u is related to ?x by :sim.
+#
+# We record class equality using the ordinary relation:
+#
+#   (?x ?y) :sameClass true.
+# ===============================================================
+
+@prefix :    <http://example.org/#>.
+@prefix log: <http://www.w3.org/2000/10/swap/log#>.
+
+# ------------------
+# Carrier membership
+# ------------------
+# We use:
+#
+#   ?x :inX true.
+#
+# to indicate that ?x belongs to the underlying set X.
+
+# ---------------------------------
+# Axioms of an equivalence relation
+# ---------------------------------
+
+# Reflexive:
+# every element is related to itself
+
+{
+  ?x :inX true.
+}
+=>
+{
+  ?x :sim ?x.
+}.
+
+# Symmetric:
+# if x ~ y then y ~ x
+
+{
+  ?x :sim ?y.
+}
+=>
+{
+  ?y :sim ?x.
+}.
+
+# Transitive:
+# if x ~ y and y ~ z then x ~ z
+
+{
+  ?x :sim ?y.
+  ?y :sim ?z.
+}
+=>
+{
+  ?x :sim ?z.
+}.
+
+
+# -------------------
+# Equivalence classes
+# -------------------
+# Membership in the class of x is just another way to say
+# "is related to x".
+
+{
+  ?u :sim ?x.
+}
+=>
+{
+  ?u :inClassOf ?x.
+}.
+
+# If x ~ y, then x and y determine the same class.
+
+{
+  ?x :sim ?y.
+}
+=>
+{
+  (?x ?y) :sameClass true.
+}.
+
+# Symmetry of class equality
+
+{
+  (?x ?y) :sameClass true.
+}
+=>
+{
+  (?y ?x) :sameClass true.
+}.
+
+
+# -----------
+# The theorem
+# -----------
+# Proof idea:
+#
+#   if z is in [x] and z is in [y],
+#   then z ~ x and z ~ y
+#   so x ~ z          by symmetry
+#   and x ~ y         by transitivity
+#   hence [x] = [y]
+#
+# The actual class equality comes from the earlier rules.
+# This rule simply packages the result as an explicit theorem
+# instance with a witness ?z.
+
+{
+  ?z :inClassOf ?x.
+  ?z :inClassOf ?y.
+  (?x ?y) :sameClass true.
+}
+=>
+{
+  (?x ?y ?z) :sharedMemberShowsSameClass true.
+}.
+
+
+# -----------------
+# Tiny example data
+# -----------------
+# Here :b belongs to both the class of :a and the class of :c,
+# because we assert:
+#
+#   b ~ a
+#   b ~ c
+#
+# From the axioms, the reasoner should conclude that
+# the classes of :a and :c are the same.
+
+:a :inX true.
+:b :inX true.
+:c :inX true.
+
+:b :sim :a.
+:b :sim :c.
+
+
+# -----
+# Query
+# -----
+# Ask for non-trivial cases where a shared member forces
+# two classes to be the same.
+
+{
+  (?x ?y ?z) :sharedMemberShowsSameClass true.
+  ?x log:notEqualTo ?y.
+}
+log:query
+{
+  :result :sameClassBecauseOfSharedMember (?x ?y ?z).
+}.

package/examples/french-cities.n3

@@ -29,3 +29,5 @@
 # OWL rules
 {?P a owl:TransitiveProperty. ?S ?P ?X. ?X ?P ?O.} => {?S ?P ?O}.
 
+# query
+{?C :path :nantes} log:query {?C :path :nantes}.

package/examples/greatest-lower-bound-uniqueness.n3

@@ -0,0 +1,202 @@
+# ===========================================================
+# File: greatest-lower-bound-uniqueness.n3
+#
+# Purpose
+# -------
+# This file expresses a pure mathematical result:
+#
+#   In a partial order, a greatest lower bound is unique.
+#
+# Core idea
+# ---------
+# We choose a framework with a relation :leq and the usual
+# order-theoretic laws. Then we introduce the notion of a
+# greatest lower bound of two elements.
+#
+# Once those choices are fixed, the following is no longer
+# optional:
+#
+#   if ?m and ?n are both greatest lower bounds of ?a and ?b,
+#   then they must be the same.
+#
+# So again:
+#   the framework is chosen,
+#   but the consequence is forced.
+#
+# Representation
+# --------------
+#   ?x :leq ?y
+# means:
+#   x ≤ y
+#
+#   ?m :glbOf (?a ?b)
+# means:
+#   m is a greatest lower bound of a and b
+#
+#   (?x ?y) :sameTerm true
+# records provable sameness as an ordinary derived fact.
+# ===========================================================
+
+@prefix :    <http://example.org/#>.
+@prefix log: <http://www.w3.org/2000/10/swap/log#>.
+
+# ------------------
+# Carrier membership
+# ------------------
+
+# We use:
+#
+#   ?x :inP true.
+#
+# to indicate that ?x belongs to the underlying partially
+# ordered set.
+
+
+# -------------------------
+# Axioms of a partial order
+# -------------------------
+
+# Reflexive:
+# every element is ≤ itself
+
+{
+  ?x :inP true.
+}
+=>
+{
+  ?x :leq ?x.
+}.
+
+# Transitive:
+# if x ≤ y and y ≤ z then x ≤ z
+
+{
+  ?x :leq ?y.
+  ?y :leq ?z.
+}
+=>
+{
+  ?x :leq ?z.
+}.
+
+# Antisymmetric:
+# if x ≤ y and y ≤ x then x and y are the same
+
+{
+  ?x :leq ?y.
+  ?y :leq ?x.
+}
+=>
+{
+  (?x ?y) :sameTerm true.
+}.
+
+# Symmetry of provable sameness
+
+{
+  (?x ?y) :sameTerm true.
+}
+=>
+{
+  (?y ?x) :sameTerm true.
+}.
+
+
+# ------------
+# Lower bounds
+# ------------
+
+# If m is declared to be a greatest lower bound of a and b,
+# then m is in particular a lower bound of a and b.
+
+{
+  ?m :glbOf (?a ?b).
+}
+=>
+{
+  ?m :lowerBoundOf (?a ?b).
+  ?m :leq ?a.
+  ?m :leq ?b.
+}.
+
+# Greatestness:
+# if m is a greatest lower bound of a and b, and l is any
+# lower bound of a and b, then l ≤ m.
+
+{
+  ?m :glbOf (?a ?b).
+  ?l :lowerBoundOf (?a ?b).
+}
+=>
+{
+  ?l :leq ?m.
+}.
+
+
+# -------------------------------------------
+# Theorem: uniqueness of greatest lower bound
+# -------------------------------------------
+#
+# Proof idea:
+#
+#   Suppose m and n are both greatest lower bounds of a and b.
+#
+#   Since n is a lower bound, and m is greatest among all lower
+#   bounds, we get:
+#
+#     n ≤ m
+#
+#   Similarly:
+#
+#     m ≤ n
+#
+#   By antisymmetry:
+#
+#     m = n
+#
+# We record the result in two stages:
+#   1. derive :sameTerm
+#   2. package the theorem as :sameGlb
+
+{
+  ?m :glbOf (?a ?b).
+  ?n :glbOf (?a ?b).
+  (?m ?n) :sameTerm true.
+}
+=>
+{
+  (?a ?b ?m ?n) :sameGlb true.
+}.
+
+
+# -----------------
+# Tiny example data
+# -----------------
+# We declare two differently named candidates :g1 and :g2
+# as greatest lower bounds of the same pair (:a, :b).
+#
+# The theory should force them to coincide.
+
+:a  :inP true.
+:b  :inP true.
+:g1 :inP true.
+:g2 :inP true.
+
+:g1 :glbOf (:a :b).
+:g2 :glbOf (:a :b).
+
+
+# -----
+# Query
+# -----
+# Ask for non-trivial cases where two differently named
+# greatest lower bounds must coincide.
+
+{
+  (?a ?b ?m ?n) :sameGlb true.
+  ?m log:notEqualTo ?n.
+}
+log:query
+{
+  :result :sameGreatestLowerBound (?a ?b ?m ?n).
+}.