eyeling 1.21.1 → 1.21.3

package/HANDBOOK.md

@@ -31,6 +31,7 @@
 - [Appendix D — LLM + Eyeling: A Repeatable Logic Toolchain](#app-d)
 - [Appendix E — How Eyeling reaches 100% on `notation3tests`](#app-e)
 - [Appendix F — The ARC approach: Answer • Reason Why • Check](#app-f)
+- [Appendix G — Eyeling and the W3C CG Notation3 Semantics](#app-g)
 
 ---
 
@@ -2141,7 +2142,7 @@ In practice, this means:
 - builtin module loading accepts only the documented export forms
 - the helper API exposed by `__buildBuiltinRegistrationApi()` has a fixed key set
 - builtin handlers should return an array of substitution objects
-- accidental helper drift is caught by `test/builtin-contract.test.js`
+- accidental helper drift is caught by `test/builtins.test.js`
 
 This is only meant to stop silent breakage. It is **not** a promise that Eyeling can never change the builtin API. If the helper surface ever needs to change, that change should be deliberate, documented, and called out in release notes.
 
@@ -3104,3 +3105,63 @@ A file really follows ARC only when the answer, the explanation, and the validat
 ### F.9 Why this style is worth using
 
 This style is worth using because it makes an Eyeling file easier to run, easier to inspect, and easier to trust. The result is visible. The key reason is visible. The check is visible. That makes examples better teaching material, makes policy or computation examples easier to audit, and makes the whole file more reusable as a small reasoning artifact instead of an opaque session transcript.
+
+<a id="app-g"></a>
+
+## Appendix G — Eyeling and the W3C CG Notation3 Semantics
+
+The purpose of this appendix is to say where Eyeling tracks the [W3C CG Notation3 semantics](https://w3c.github.io/N3/spec/semantics) closely, and where Eyeling makes deliberate operational choices of its own.
+
+The comparison point here is the W3C CG Notation3 semantics document, not a claim that Eyeling is trying to be a line-by-line implementation of that document. Eyeling is a working reasoner, so some choices are shaped by execution, indexing, determinism, and the practical habits of N3 authors.
+
+### G.1 Where Eyeling is strongly aligned
+
+- **Core term model (IRIs, literals, variables, blank nodes, lists, quoted formulas):** The semantics document treats N3 terms as IRIs, literals, variables, lists, and graph terms. Eyeling’s internal model matches that shape directly through `Iri`, `Literal`, `Var`, `Blank`, `ListTerm`, and `GraphTerm`.
+
+- **Quoted formulas need alpha-equivalence / isomorphism:** The semantics document defines isomorphism for graphs and graph terms using consistent renaming. Eyeling implements the same practical idea operationally as alpha-equivalence for `GraphTerm`, with consistent renaming as the criterion for a match.
+
+- **Rules as implication (and `true` as empty formula):** The semantics document gives a special role to `log:implies` and treats `true` and `false` specially, with `true` corresponding to the empty formula. Eyeling follows that shape: it accepts both `{ P } => { C }` and `{ P } log:implies { C }`, and it treats `true` as `{}`.
+
+- **Lists as first-class citizens (not just RDF collections):** The semantics document treats lists as genuine N3 terms. Eyeling does the same through `ListTerm`, and also materializes RDF `rdf:first` / `rdf:rest` chains into list terms so one list model can be used throughout the engine.
+
+### G.2 Where Eyeling diverges or goes beyond the semantics document
+
+#### G.2.1 Blank nodes in rule bodies: Eyeling chooses common N3 rule-writing practice
+
+The semantics document describes blank nodes as existentially quantified with local scope. Eyeling intentionally rewrites blank nodes in **rule premises** into variables during normalization. In practice this makes body blanks behave like the placeholders many N3 authors expect when they write rules.
+
+That is a real semantic choice. It is useful and intentional, but it is not the same as reading blank nodes as existentials everywhere.
+
+#### G.2.2 Groundness of quoted formulas containing variables
+
+In the semantics document, whether a graph term is ground depends on whether the underlying graph is closed, and nested formulas can still contain free variables when viewed in isolation. Eyeling makes a pragmatic engine choice: variables inside a `GraphTerm` do not make the surrounding triple non-ground. In the handbook this is summarized as “variables inside formulas do not leak.”
+
+That supports indexing, matching, and duplicate checks, but it is not a one-to-one restatement of model-theoretic groundness for graph terms.
+
+#### G.2.3 Eyeling defines operational behavior beyond what the semantics document currently fixes
+
+The semantics document mainly fixes meaning around implication and the core N3 term/formula model. Eyeling goes further and gives operational meaning to a large standard library of builtins and control features. Examples include `math:*`, `string:*`, `list:*`, `time:*`, `log:includes`, `log:notIncludes`, `log:query`, and scoped closure via `log:conclusion`.
+
+So Eyeling is not only implementing the semantics document; it is also defining engine behavior for features that the current document does not fully specify.
+
+#### G.2.4 Inference fuses (`=> false`) are an engine-level procedural feature
+
+The semantics document discusses `false` in relation to implication and constraints. Eyeling turns `{ ... } => false` into an engine-level hard failure with a visible message and failing exit status. That is a practical tooling feature: it lets a rule act like a checked invariant.
+
+This is very useful in real programs, but it is an operational behavior of the reasoner, not something a model-theoretic semantics “executes.”
+
+#### G.2.5 Surface-language coverage is not the same thing as semantic alignment
+
+The semantics document discusses explicit quantification in its abstract syntax. Eyeling mostly exposes implicit quantification through `?x` variables and blank nodes, together with the rule-normalization choices described earlier. The handbook documents the supported surface forms Eyeling actually parses, which may be narrower than the full abstract surface discussed in the semantics document.
+
+So even where the underlying ideas line up, the accepted concrete syntax may still be a proper subset.
+
+### G.3 The practical takeaway
+
+A good short summary is this:
+
+- Eyeling is strongly aligned with the N3 semantics on the **core ontology of terms, quoted formulas, implication, and lists**.
+- Eyeling makes deliberate, implementation-shaped choices around **rule-body blanks, groundness of quoted formulas, and constraint execution**.
+- Eyeling also defines a wider operational language than the current semantics document, especially through builtins and scoped proof/query features.
+
+So the handbook and the semantics document are best read as complementary. The semantics document explains the abstract shape of Notation3. The handbook explains how a compact working reasoner realizes that shape, and where it chooses a practical execution model over a purely model-theoretic presentation.

package/README.md

@@ -16,5 +16,4 @@ echo '@prefix : <http://example.org/> .
 
 - **Handbook:** [eyereasoner.github.io/eyeling/HANDBOOK](https://eyereasoner.github.io/eyeling/HANDBOOK)
 - **Playground:** [eyereasoner.github.io/eyeling/demo](https://eyereasoner.github.io/eyeling/demo)
-- **Semantics:** [eyereasoner.github.io/eyeling/SEMANTICS](https://eyereasoner.github.io/eyeling/SEMANTICS)
 - **Conformance report:** [codeberg.org/phochste/notation3tests/.../report.md](https://codeberg.org/phochste/notation3tests/src/branch/main/reports/report.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.21.1",
+  "version": "1.21.3",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [
@@ -22,7 +22,6 @@
     "LICENSE.md",
     "README.md",
     "HANDBOOK.md",
-    "SEMANTICS.md",
     "eyeling-builtins.ttl",
     "eyeling.js",
     "index.js",
@@ -42,14 +41,14 @@
     "build": "node tools/bundle.js",
     "test:packlist": "node test/packlist.test.js",
     "test:api": "node test/api.test.js",
-    "test:builtin-contract": "node test/builtin-contract.test.js",
+    "test:builtins": "node test/builtins.test.js",
     "test:n3gen": "node test/n3gen.test.js",
     "test:examples": "node test/examples.test.js",
     "test:extra": "node test/extra.test.js",
     "test:manifest": "node test/manifest.test.js",
     "test:playground": "node test/playground.test.js",
     "test:package": "node test/package.test.js",
-    "test:all": "npm run test:api && npm run test:builtin-contract && npm run test:n3gen && npm run test:examples && npm run test:extra && npm run test:manifest && npm run test:playground",
+    "test:all": "npm run test:api && npm run test:builtins && npm run test:n3gen && npm run test:examples && npm run test:extra && npm run test:manifest && npm run test:playground",
     "pretest": "npm run build && npm run test:packlist",
     "test": "npm run test:all",
     "posttest": "npm run test:package",

package/test/{builtin-contract.test.js → builtins.test.js}

@@ -1,7 +1,6 @@
 'use strict';
 
 const assert = require('node:assert/strict');
-const path = require('node:path');
 
 const TTY = process.stdout.isTTY;
 const C = TTY
@@ -18,7 +17,6 @@ function fail(msg) {
   console.error(`${C.r}FAIL${C.n} ${msg}`);
 }
 
-const fixtures = path.join(__dirname, 'fixtures', 'builtins');
 const builtins = require('../lib/builtins');
 require('../lib/engine');
 
@@ -62,8 +60,43 @@ const expectedTermsKeys = [
   'Triple',
   'Rule',
 ].sort();
+
 const expectedNsKeys = ['RDF_NS', 'XSD_NS', 'CRYPTO_NS', 'MATH_NS', 'TIME_NS', 'LIST_NS', 'LOG_NS', 'STRING_NS'].sort();
 
+function makeOkMapModule() {
+  return {
+    'http://example.org/test#ok': ({ subst }) => [subst],
+  };
+}
+
+function makeOkRegisterModule() {
+  return {
+    register(api) {
+      api.registerBuiltin('http://example.org/test#ok-register', ({ subst }) => [subst]);
+    },
+  };
+}
+
+function makeOkBuiltinsModule() {
+  return {
+    builtins: {
+      'http://example.org/test#ok-builtins': ({ subst }) => [subst],
+    },
+  };
+}
+
+function makeOkDefaultMapModule() {
+  return {
+    default: {
+      'http://example.org/test#ok-default-map': ({ subst }) => [subst],
+    },
+  };
+}
+
+function makeBadExportModule() {
+  return 42;
+}
+
 const cases = [
   {
     name: 'builtin helper API stays stable and frozen',
@@ -80,23 +113,17 @@ const cases = [
   {
     name: 'registerBuiltinModule accepts supported module export forms',
     run() {
-      assert.doesNotThrow(() => builtins.registerBuiltinModule(require(path.join(fixtures, 'ok-map.js')), 'ok-map'));
-      assert.doesNotThrow(() =>
-        builtins.registerBuiltinModule(require(path.join(fixtures, 'ok-register.js')), 'ok-register'),
-      );
-      assert.doesNotThrow(() =>
-        builtins.registerBuiltinModule(require(path.join(fixtures, 'ok-builtins.js')), 'ok-builtins'),
-      );
-      assert.doesNotThrow(() =>
-        builtins.registerBuiltinModule(require(path.join(fixtures, 'ok-default-map.js')), 'ok-default-map'),
-      );
+      assert.doesNotThrow(() => builtins.registerBuiltinModule(makeOkMapModule(), 'ok-map'));
+      assert.doesNotThrow(() => builtins.registerBuiltinModule(makeOkRegisterModule(), 'ok-register'));
+      assert.doesNotThrow(() => builtins.registerBuiltinModule(makeOkBuiltinsModule(), 'ok-builtins'));
+      assert.doesNotThrow(() => builtins.registerBuiltinModule(makeOkDefaultMapModule(), 'ok-default-map'));
     },
   },
   {
     name: 'registerBuiltinModule rejects unsupported module exports',
     run() {
       assert.throws(
-        () => builtins.registerBuiltinModule(require(path.join(fixtures, 'bad-export.js')), 'bad-export'),
+        () => builtins.registerBuiltinModule(makeBadExportModule(), 'bad-export'),
         /must export a function, a \{ register\(\) \} object, or an object mapping predicate IRIs to handlers/,
       );
     },

package/SEMANTICS.md

@@ -1,41 +0,0 @@
-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/test/fixtures/builtins/bad-export.js

@@ -1,3 +0,0 @@
-'use strict';
-
-module.exports = 42;

package/test/fixtures/builtins/ok-builtins.js

@@ -1,7 +0,0 @@
-'use strict';
-
-module.exports = {
-  builtins: {
-    'http://example.org/test#ok-builtins': ({ subst }) => [subst],
-  },
-};

package/test/fixtures/builtins/ok-default-map.js

@@ -1,7 +0,0 @@
-'use strict';
-
-module.exports = {
-  default: {
-    'http://example.org/test#ok-default-map': ({ subst }) => [subst],
-  },
-};

package/test/fixtures/builtins/ok-map.js

@@ -1,5 +0,0 @@
-'use strict';
-
-module.exports = {
-  'http://example.org/test#ok': ({ subst }) => [subst],
-};

package/test/fixtures/builtins/ok-register.js

@@ -1,7 +0,0 @@
-'use strict';
-
-module.exports = {
-  register(api) {
-    api.registerBuiltin('http://example.org/test#ok-register', ({ subst }) => [subst]);
-  },
-};