eyeling 1.19.4 → 1.19.5

package/HANDBOOK.md

@@ -2955,104 +2955,50 @@ That is why the result is 100%.
 
 ## Appendix F — The ARC approach: Answer • Reason Why • Check
 
-A useful way to structure an Eyeling program is the ARC approach:
+A simple way to write a good Eyeling program is to make it do three things in one file:
 
-> Answer • Reason Why • Check
+> give the answer, say why, and check that it really holds.
 
-The idea is simple: do not stop at producing a result. Produce the result, explain why it is the right result, and include a concrete verification that fails loudly when an important assumption does not hold.
+That is the ARC approach: **Answer • Reason Why • Check**.
 
-ARC treats a program as a small, accountable artifact built from three ingredients:
+The idea is not to make the program more grand or formal. It is to make it more useful. A bare result is often not enough. A reader also wants to see the small reason that matters, and to know that the program will fail loudly if an important assumption is wrong.
 
-1. Data
-2. Logic
-3. A Question
+In Eyeling this style comes quite naturally. Facts hold the data. Rules derive the conclusion. `log:outputString` can turn the conclusion into readable output. And a rule that concludes `false` acts as a fuse: if a bad condition becomes provable, the run stops instead of quietly producing a misleading result.
 
-From these, we build a compact program that answers the question, explains the answer, and checks itself.
+### F.1 What the three parts mean
 
-### F.1 The three parts
+The **Answer** is the direct result. It should be short and easy to recognize. In many Eyeling files it is a final recommendation, a route, a computed value, a decision such as `allowed` or `blocked`, or a small report line emitted with `log:outputString`.
 
-#### Answer
+The **Reason Why** is the compact explanation. It is not hidden chain-of-thought and it does not need to be long. Usually it is just the witness, threshold, policy, path, or intermediate fact that made the answer follow. A good reason tells the reader what mattered.
 
-The **Answer** is the direct response to the question being asked.
+The **Check** is the part that keeps the program honest. It should do more than repeat the answer in different words. A good check tests something that could really fail: a structural invariant, a recomputed quantity, a boundary condition, or a rule that derives `false` when the answer would be inconsistent with the inputs.
 
-It should be short, specific, and easy to read. In Eyeling, this is often emitted as one or more `log:outputString` lines such as:
+A short way to remember ARC is this:
 
-- the final decision
-- the selected item
-- the computed value
-- the resulting classification
+> an answer tells you **what** happened, a reason tells you **why**, and a check tells you **whether you should trust it**.
 
-A good Answer reads like something you could show to a user, an auditor, or a calling program.
+### F.2 Why this fits Eyeling well
 
-#### Reason Why
+ARC is not an extra subsystem in Eyeling. It is mostly a good habit.
 
-The **Reason Why** explains why the Answer is correct.
+Eyeling already separates data from logic. It already lets you derive readable output instead of printing ad hoc text during proof search. And it already has a very strong notion of validation through inference fuses. So ARC is really just a clean way to organize an ordinary Eyeling file so that a human reader can see the result, the explanation, and the safety net together.
 
-This is not a full proof calculus or a hidden chain of thought. It is a concise, inspectable explanation grounded in the facts, rules, thresholds, identities, or policies that matter for the case. In practice, it often includes:
+This is especially useful for examples. A newcomer can run the file and see what it does. A maintainer can inspect the few rules that justify the result. And an external developer can tell whether the example merely prints something nice or actually checks itself.
 
-- the relevant inputs
-- the governing rule or policy
-- the key intermediate facts
-- the condition that made the conclusion follow
+### F.3 A simple pattern to follow
 
-In Eyeling, the Reason Why is usually rendered as additional `log:outputString` lines derived from the same closure as the Answer.
+A practical ARC-style Eyeling file often has four visible layers.
 
-#### Check
+First come the **facts**: the input data, parameters, thresholds, policies, or known relationships. Then comes the **logic**: the rules that derive the internal conclusion. Then comes the **presentation**: rules that turn the result into `log:outputString` lines or other report facts. Finally come the **checks**: rules that validate the result or trigger `false` when an invariant is broken.
 
-The **Check** is an independent validation step.
+You do not have to separate these layers perfectly, but it helps a lot when the file reads in roughly that order.
 
-Its purpose is not to restate the Answer, but to test that important invariants still hold. A Check should fail loudly if the program’s assumptions break, if a data dependency is malformed, or if an edge case invalidates the intended conclusion.
-
-In Eyeling, Checks are a natural fit for either:
-
-- derived facts such as `:ok :signatureVerified true .`, or
-- inference fuses such as `{ ... } => false .` when a violation must stop execution.
-
-This makes verification part of the program itself rather than something left to external commentary.
-
-### F.2 Proof = Reason Why + Check
-
-ARC summarizes its trust model as:
-
-> Proof = Reason Why + Check
-
-That is a practical notion of proof. The Reason Why explains the logic in human terms. The Check verifies that the critical conditions actually hold at runtime.
-
-For many real workflows, that combination is more useful than a bare result: it is inspectable, repeatable, and suitable for automation.
-
-### F.3 Why ARC fits Eyeling well
-
-Eyeling already encourages the separation that ARC needs.
-
-Rules derive facts. Facts can include output facts. Output is not printed eagerly during proof search; instead, `log:outputString` facts are collected from the final closure and rendered deterministically whenever they are present. This makes it natural to derive a structured Answer and Reason Why as part of the logic itself.
-
-Checks also map well to Eyeling. A rule with conclusion `false` acts as an inference fuse: if its body becomes provable, execution stops with a hard failure. This is exactly the behavior we want for “must-hold” conditions.
-
-So ARC in Eyeling is not an add-on. It is mostly a disciplined way of organizing what Eyeling already does well: derive conclusions, expose supporting facts, and enforce invariants.
-
-### F.4 A practical pattern
-
-A simple ARC-oriented Eyeling file often has four layers:
-
-1. **Facts**  
-   Input data, parameters, policies, and known relationships.
-
-2. **Logic**  
-   Rules that derive the program’s internal conclusions.
-
-3. **Presentation**  
-   Rules that turn derived conclusions into `log:outputString` lines for the Answer and Reason Why.
-
-4. **Verification**  
-   Rules that derive check facts or trigger inference fuses on violations.
-
-A useful habit is to keep these layers visually separate in the file.
-
-### F.5 A tiny template
+### F.4 A tiny template
 
 ```n3
 @prefix : <http://example.org/> .
 @prefix log: <http://www.w3.org/2000/10/swap/log#> .
+@prefix math: <http://www.w3.org/2000/10/swap/math#> .
 
 # Facts
 :case :input 42 .
@@ -3078,25 +3024,38 @@ A useful habit is to keep these layers visually separate in the file.
     => false .
 ```
 
-The exact presentation style can vary, but the shape remains the same: derive the result, explain the result, and verify the result.
+The exact wording can vary. The important thing is the shape: derive the result, make the key reason visible, and include at least one check that could fail for a real reason.
+
+### F.5 What a good check looks like
+
+A good check is not a decorative `:ok true` line. It should add real confidence.
+
+Sometimes that means recomputing a quantity from another angle. Sometimes it means checking a witness path instead of only the summary result. Sometimes it means making sure a threshold really was crossed, or that a list or graph has the shape the rest of the program assumes. And sometimes the right check is simply an inference fuse that says: if this contradiction appears, stop.
+
+The point is not to make checks large. The point is to make them real.
+
+### F.6 Examples in `examples/` that read well in ARC style
+
+The following examples are especially good places to see this style in practice.
+
+- [`examples/delfour.n3`](examples/delfour.n3) — privacy-preserving shopping assistance with a concrete recommendation, an explanation, and policy checks. Expected output: [`examples/output/delfour.n3`](examples/output/delfour.n3)
+- [`examples/control-system.n3`](examples/control-system.n3) — derives actuator decisions, explains the control basis, and checks the result. Expected output: [`examples/output/control-system.n3`](examples/output/control-system.n3)
+- [`examples/deep-taxonomy-100000.n3`](examples/deep-taxonomy-100000.n3) — a deep classification stress test whose answer is whether the final goal class is reached. Expected output: [`examples/output/deep-taxonomy-100000.n3`](examples/output/deep-taxonomy-100000.n3)
+- [`examples/gps.n3`](examples/gps.n3) — route planning with readable route output. Expected output: [`examples/output/gps.n3`](examples/output/gps.n3)
+- [`examples/sudoku.n3`](examples/sudoku.n3) — solver output plus legality and consistency checks. Expected output: [`examples/output/sudoku.n3`](examples/output/sudoku.n3)
 
-### F.6 What ARC is not
+### F.7 How to read an ARC-style example
 
-ARC does **not** mean:
+A good way to read one of these files is to start with the question in the comments or input facts. Then find the part that gives the answer. Then trace the few rules that explain why that answer follows. Finally, look for the checks: the validation facts, the recomputation, or the `=> false` fuse that would stop the run if something important were wrong.
 
-- printing a result and calling it explained
-- replacing checks with prose
-- hiding the important assumptions
-- relying on “trust me” comments outside the executable artifact
+That reading order keeps the example grounded in observable behavior rather than in source code alone.
 
-A file follows ARC only when the answer, explanation, and validation are all carried by the program itself.
+### F.8 What ARC is not
 
-### F.7 A good default for examples
+ARC does not mean wrapping every file in ceremony. It does not mean long prose explanations. It does not mean hiding important assumptions in comments while the executable part stays thin. And it does not mean replacing checks with a confident tone.
 
-For worked examples in this handbook, ARC is a strong default presentation style:
+A file really follows ARC only when the answer, the explanation, and the validation all live in the program itself.
 
-- **Answer** for the main result
-- **Reason Why** for the key supporting explanation
-- **Check** for invariants and fail-loud validation
+### F.9 Why this style is worth using
 
-This keeps examples readable for newcomers while also making them more useful as reusable, auditable logic artifacts.
+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.

package/examples/fibonacci.n3

@@ -23,6 +23,7 @@
     10 :fibonacci ?F10.
     100 :fibonacci ?F100.
     1000 :fibonacci ?F1000.
+    10000 :fibonacci ?F10000.
 } => {
     :test :is {
         0 :fibonacci ?F0.
@@ -30,6 +31,7 @@
         10 :fibonacci ?F10.
         100 :fibonacci ?F100.
         1000 :fibonacci ?F1000.
+        10000 :fibonacci ?F10000.
     }.
 }.
 

package/examples/output/fibonacci.n3

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

package/eyeling.js

@@ -8133,6 +8133,18 @@ function __printTriggeredFuse(rule, prefixes, subst /* optional */, extraNote /*
   }
 }
 
+function __exitReasoning(code, message /* optional */) {
+  if (typeof process !== 'undefined' && process && typeof process.exit === 'function') {
+    process.exit(code);
+    return;
+  }
+
+  const err = new Error(message || `Process exited with code ${code}`);
+  err.__eyelingExit = true;
+  err.code = code;
+  throw err;
+}
+
 function forwardChain(facts, forwardRules, backRules, onDerived /* optional */, opts = {}) {
   enterReasoningRun();
   try {
@@ -8272,7 +8284,7 @@ function forwardChain(facts, forwardRules, backRules, onDerived /* optional */,
         // Allow dynamic fuses: ... => ?X. where ?X becomes false
         if (dynTerm instanceof Literal && dynTerm.value === 'false') {
           __printTriggeredFuse(r, opts && opts.prefixes, s, 'Dynamic head resolved to false.');
-          process.exit(2);
+          __exitReasoning(2, 'Inference fuse triggered.');
         }
 
         const dynTriples = __graphTriplesOrTrue(dynTerm);
@@ -8300,10 +8312,10 @@ function forwardChain(facts, forwardRules, backRules, onDerived /* optional */,
         const objIsGraph = obj instanceof GraphTerm;
         const subjIsTrue = subj instanceof Literal && subj.value === 'true';
         const objIsTrue = obj instanceof Literal && obj.value === 'true';
+        const objIsFalse = obj instanceof Literal && obj.value === 'false';
 
         const isFwRuleTriple =
-          isLogImplies(instantiated.p) &&
-          ((subjIsGraph && objIsGraph) || (subjIsTrue && objIsGraph) || (subjIsGraph && objIsTrue));
+          isLogImplies(instantiated.p) && (subjIsGraph || subjIsTrue) && (objIsGraph || objIsTrue || objIsFalse);
 
         const isBwRuleTriple =
           isLogImpliedBy(instantiated.p) &&
@@ -8318,47 +8330,39 @@ function forwardChain(facts, forwardRules, backRules, onDerived /* optional */,
             changedHere = true;
           }
 
-          // Promote rule-producing triples to live rules, treating literal true as {}.
-          const left = __graphTriplesOrTrue(subj);
-          const right = __graphTriplesOrTrue(obj);
-
-          if (left !== null && right !== null) {
-            if (isFwRuleTriple) {
-              const [premise, conclusion] = liftBlankRuleVars(left, right);
-              const headBlankLabels = collectBlankLabelsInTriples(conclusion);
-              const newRule = new Rule(premise, conclusion, true, false, headBlankLabels);
-              __prepareForwardRule(newRule);
-
-              const key = __ruleKey(
-                newRule.isForward,
-                newRule.isFuse,
-                newRule.premise,
-                newRule.conclusion,
-                newRule.__dynamicConclusionTerm || null,
-              );
-              if (!forwardRules.__ruleKeySet.has(key)) {
-                forwardRules.__ruleKeySet.add(key);
-                forwardRules.push(newRule);
-                rulesChanged = true;
-              }
-            } else if (isBwRuleTriple) {
-              const [premise, conclusion] = liftBlankRuleVars(right, left);
-              const headBlankLabels = collectBlankLabelsInTriples(conclusion);
-              const newRule = new Rule(premise, conclusion, false, false, headBlankLabels);
-
-              const key = __ruleKey(
-                newRule.isForward,
-                newRule.isFuse,
-                newRule.premise,
-                newRule.conclusion,
-                newRule.__dynamicConclusionTerm || null,
-              );
-              if (!backRules.__ruleKeySet.has(key)) {
-                backRules.__ruleKeySet.add(key);
-                backRules.push(newRule);
-                indexBackRule(backRules, newRule);
-                rulesChanged = true;
-              }
+          // Promote rule-producing triples to live rules, treating literal true as {}
+          // and literal false as a fuse head.
+          if (isFwRuleTriple) {
+            const newRule = __makeRuleFromTerms(subj, obj, true);
+            __prepareForwardRule(newRule);
+
+            const key = __ruleKey(
+              newRule.isForward,
+              newRule.isFuse,
+              newRule.premise,
+              newRule.conclusion,
+              newRule.__dynamicConclusionTerm || null,
+            );
+            if (!forwardRules.__ruleKeySet.has(key)) {
+              forwardRules.__ruleKeySet.add(key);
+              forwardRules.push(newRule);
+              rulesChanged = true;
+            }
+          } else if (isBwRuleTriple) {
+            const newRule = __makeRuleFromTerms(subj, obj, false);
+
+            const key = __ruleKey(
+              newRule.isForward,
+              newRule.isFuse,
+              newRule.premise,
+              newRule.conclusion,
+              newRule.__dynamicConclusionTerm || null,
+            );
+            if (!backRules.__ruleKeySet.has(key)) {
+              backRules.__ruleKeySet.add(key);
+              backRules.push(newRule);
+              indexBackRule(backRules, newRule);
+              rulesChanged = true;
             }
           }
 
@@ -8441,7 +8445,7 @@ function forwardChain(facts, forwardRules, backRules, onDerived /* optional */,
           // Inference fuse
           if (r.isFuse && sols.length) {
             __printTriggeredFuse(r, opts && opts.prefixes, sols[0]);
-            process.exit(2);
+            __exitReasoning(2, 'Inference fuse triggered.');
           }
 
           for (const s of sols) {

package/lib/engine.js

@@ -2651,6 +2651,18 @@ function __printTriggeredFuse(rule, prefixes, subst /* optional */, extraNote /*
   }
 }
 
+function __exitReasoning(code, message /* optional */) {
+  if (typeof process !== 'undefined' && process && typeof process.exit === 'function') {
+    process.exit(code);
+    return;
+  }
+
+  const err = new Error(message || `Process exited with code ${code}`);
+  err.__eyelingExit = true;
+  err.code = code;
+  throw err;
+}
+
 function forwardChain(facts, forwardRules, backRules, onDerived /* optional */, opts = {}) {
   enterReasoningRun();
   try {
@@ -2790,7 +2802,7 @@ function forwardChain(facts, forwardRules, backRules, onDerived /* optional */,
         // Allow dynamic fuses: ... => ?X. where ?X becomes false
         if (dynTerm instanceof Literal && dynTerm.value === 'false') {
           __printTriggeredFuse(r, opts && opts.prefixes, s, 'Dynamic head resolved to false.');
-          process.exit(2);
+          __exitReasoning(2, 'Inference fuse triggered.');
         }
 
         const dynTriples = __graphTriplesOrTrue(dynTerm);
@@ -2818,10 +2830,10 @@ function forwardChain(facts, forwardRules, backRules, onDerived /* optional */,
         const objIsGraph = obj instanceof GraphTerm;
         const subjIsTrue = subj instanceof Literal && subj.value === 'true';
         const objIsTrue = obj instanceof Literal && obj.value === 'true';
+        const objIsFalse = obj instanceof Literal && obj.value === 'false';
 
         const isFwRuleTriple =
-          isLogImplies(instantiated.p) &&
-          ((subjIsGraph && objIsGraph) || (subjIsTrue && objIsGraph) || (subjIsGraph && objIsTrue));
+          isLogImplies(instantiated.p) && (subjIsGraph || subjIsTrue) && (objIsGraph || objIsTrue || objIsFalse);
 
         const isBwRuleTriple =
           isLogImpliedBy(instantiated.p) &&
@@ -2836,47 +2848,39 @@ function forwardChain(facts, forwardRules, backRules, onDerived /* optional */,
             changedHere = true;
           }
 
-          // Promote rule-producing triples to live rules, treating literal true as {}.
-          const left = __graphTriplesOrTrue(subj);
-          const right = __graphTriplesOrTrue(obj);
-
-          if (left !== null && right !== null) {
-            if (isFwRuleTriple) {
-              const [premise, conclusion] = liftBlankRuleVars(left, right);
-              const headBlankLabels = collectBlankLabelsInTriples(conclusion);
-              const newRule = new Rule(premise, conclusion, true, false, headBlankLabels);
-              __prepareForwardRule(newRule);
-
-              const key = __ruleKey(
-                newRule.isForward,
-                newRule.isFuse,
-                newRule.premise,
-                newRule.conclusion,
-                newRule.__dynamicConclusionTerm || null,
-              );
-              if (!forwardRules.__ruleKeySet.has(key)) {
-                forwardRules.__ruleKeySet.add(key);
-                forwardRules.push(newRule);
-                rulesChanged = true;
-              }
-            } else if (isBwRuleTriple) {
-              const [premise, conclusion] = liftBlankRuleVars(right, left);
-              const headBlankLabels = collectBlankLabelsInTriples(conclusion);
-              const newRule = new Rule(premise, conclusion, false, false, headBlankLabels);
-
-              const key = __ruleKey(
-                newRule.isForward,
-                newRule.isFuse,
-                newRule.premise,
-                newRule.conclusion,
-                newRule.__dynamicConclusionTerm || null,
-              );
-              if (!backRules.__ruleKeySet.has(key)) {
-                backRules.__ruleKeySet.add(key);
-                backRules.push(newRule);
-                indexBackRule(backRules, newRule);
-                rulesChanged = true;
-              }
+          // Promote rule-producing triples to live rules, treating literal true as {}
+          // and literal false as a fuse head.
+          if (isFwRuleTriple) {
+            const newRule = __makeRuleFromTerms(subj, obj, true);
+            __prepareForwardRule(newRule);
+
+            const key = __ruleKey(
+              newRule.isForward,
+              newRule.isFuse,
+              newRule.premise,
+              newRule.conclusion,
+              newRule.__dynamicConclusionTerm || null,
+            );
+            if (!forwardRules.__ruleKeySet.has(key)) {
+              forwardRules.__ruleKeySet.add(key);
+              forwardRules.push(newRule);
+              rulesChanged = true;
+            }
+          } else if (isBwRuleTriple) {
+            const newRule = __makeRuleFromTerms(subj, obj, false);
+
+            const key = __ruleKey(
+              newRule.isForward,
+              newRule.isFuse,
+              newRule.premise,
+              newRule.conclusion,
+              newRule.__dynamicConclusionTerm || null,
+            );
+            if (!backRules.__ruleKeySet.has(key)) {
+              backRules.__ruleKeySet.add(key);
+              backRules.push(newRule);
+              indexBackRule(backRules, newRule);
+              rulesChanged = true;
             }
           }
 
@@ -2959,7 +2963,7 @@ function forwardChain(facts, forwardRules, backRules, onDerived /* optional */,
           // Inference fuse
           if (r.isFuse && sols.length) {
             __printTriggeredFuse(r, opts && opts.prefixes, sols[0]);
-            process.exit(2);
+            __exitReasoning(2, 'Inference fuse triggered.');
           }
 
           for (const s of sols) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.19.4",
+  "version": "1.19.5",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [