eyeling 1.16.5 → 1.17.0

package/HANDBOOK.md

@@ -1537,7 +1537,7 @@ Implementation: this is implemented by `lib/trace.js` and called from `lib/engin
 
 As a goal, this builtin simply checks that the terms are sufficiently bound/usable and then succeeds. The actual “printing” behavior is handled by the CLI:
 
-- When you run Eyeling with `--strings` / `-r`, the CLI collects all `log:outputString` triples from the _saturated_ closure.
+- When the final closure contains any `log:outputString` triples, the CLI collects all of them from the _saturated_ closure and renders those strings instead of the default N3 output.
 - It sorts them deterministically by the subject “key” and concatenates the string values in that order.
 
 This is a pure test/side-effect marker (it shouldn’t drive search; it should merely validate that strings exist once other reasoning has produced them). In forward rules Eyeling may defer it if it is reached before the terms are usable.
@@ -1656,7 +1656,7 @@ Matches the regex once and returns the **first capturing group** (group 1). If t
 
 From a logic-programming point of view, printing is awkward: if you print _during_ proof search, you risk producing output along branches that later backtrack, or producing the same line multiple times in different derivations. Eyeling avoids that whole class of problems by treating “output” as **data**.
 
-The predicate `log:outputString` is the only officially supported “side-effect channel”, and even it is handled in two phases:
+The predicate `log:outputString` is the only officially supported “side-effect channel”, and even it is handled in two phases. If any final `log:outputString` facts exist, Eyeling renders them automatically as the CLI output:
 
 1. **During reasoning (declarative phase):**  
    `log:outputString` behaves like a pure test builtin (implemented in `lib/builtins.js`): it succeeds when its arguments are well-formed and sufficiently bound (notably, when the object is a string literal that can be emitted). Importantly, it does _not_ print anything at this time. If a rule derives a triple like:
@@ -1675,7 +1675,7 @@ This separation is not just an aesthetic choice; it preserves the meaning of log
 - Output becomes explainable. If you enable proof comments or inspect the closure, `log:outputString` facts can be traced back to the rules that produced them.
 - Output becomes compositional. You can reason about output strings (e.g., sort them, filter them, derive them conditionally) just like any other data.
 
-In short: Eyeling makes `log:outputString` safe by refusing to treat it as an immediate effect. It is a _declarative output fact_ whose concrete rendering is a final, deterministic post-processing step.
+In short: Eyeling makes `log:outputString` safe by refusing to treat it as an immediate effect. It is a _declarative output fact_ whose concrete rendering is a final, deterministic post-processing step. If any such facts are present in the final closure, Eyeling renders those strings automatically instead of printing the default N3 result set.
 
 ---
 
@@ -1773,7 +1773,7 @@ The bundle contains the whole engine. The CLI path is the “canonical behavior
 
 - parse input file
 - reason to closure
-- print derived triples or output strings
+- print derived triples, or render `log:outputString` strings when present
 - optional proof comments
 - optional streaming
 
@@ -1785,7 +1785,6 @@ The current CLI supports a small set of flags (see `lib/cli.js`):
 - `-d`, `--deterministic-skolem` — make `log:skolem` stable across runs.
 - `-e`, `--enforce-https` — rewrite `http://…` to `https://…` for dereferencing builtins.
 - `-p`, `--proof-comments` — include per-fact proof comment blocks in output.
-- `-r`, `--strings` — after reasoning, render only `log:outputString` values (ordered by subject key).
 - `-s`, `--super-restricted` — disable all builtins except `log:implies` / `log:impliedBy`.
 - `-t`, `--stream` — stream derived triples as soon as they are derived.
 - `-v`, `--version` — print version and exit.
@@ -1988,13 +1987,12 @@ Options:
   -e, --enforce-https          Rewrite http:// IRIs to https:// for log dereferencing builtins.
   -h, --help                   Show this help and exit.
   -p, --proof-comments         Enable proof explanations.
-  -r, --strings                Print log:outputString strings (ordered by key) instead of N3 output.
   -s, --super-restricted       Disable all builtins except => and <=.
   -t, --stream                 Stream derived triples as soon as they are derived.
   -v, --version                Print version and exit.
 ```
 
-Note: when `log:query` directives are present, Eyeling cannot stream output (the selected results depend on the saturated closure), so `--stream` has no effect in that mode.
+Note: when `log:query` directives are present, or when the program may produce `log:outputString` facts, Eyeling cannot stream its final user-facing output from partial derivations, so `--stream` has no effect in those cases. In the latter case Eyeling saturates first and then renders the collected output strings.
 
 See also:
 
@@ -2653,7 +2651,7 @@ For many real workflows, that combination is more useful than a bare result: it
 
 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, for example with `-r` / `--strings`. This makes it natural to derive a structured Answer and Reason Why as part of the logic itself.
+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.
 

package/README.md

@@ -44,7 +44,7 @@ Show all options:
 npx eyeling --help
 ```
 
-Useful flags include `--proof-comments`, `--stream`, `--strings`, and `--enforce-https`.
+Useful flags include `--proof-comments`, `--stream`, and `--enforce-https`. If the final closure contains any `log:outputString` triples, Eyeling now renders those strings automatically instead of printing N3 output.
 
 ## What gets printed?
 

package/examples/control-system.n3

@@ -1,22 +1,21 @@
-# ===========================================================================
-# Control System — ARC-style rewrite of Eyeling's control example.
-# Original example: https://raw.githubusercontent.com/eyereasoner/eyeling/refs/heads/main/examples/control-system.n3
+# =============================================================================
+# Control System — ARC-style
 #
 # This example shows how a small control system turns sensor readings into two
 # actuator commands. One command anticipates a known disturbance before it hits
 # the system. The other compares the measured output with the target and then
 # corrects the remaining gap. The ARC presentation makes the result easy to
 # inspect by giving an Answer, a clear Reason Why, and independent Checks.
-# ===========================================================================
+# =============================================================================
 
 @prefix log: <http://www.w3.org/2000/10/swap/log#>.
 @prefix math: <http://www.w3.org/2000/10/swap/math#>.
 @prefix string: <http://www.w3.org/2000/10/swap/string#>.
 @prefix : <https://example.org/control-system#>.
 
-# ---------------------------------------------------------------------------
+# -----
 # Facts
-# ---------------------------------------------------------------------------
+# -----
 
 # input
 :input1 :measurement1 (6 11).
@@ -36,9 +35,9 @@
 :output2 :measurement4 24.
 :output2 :target2 29.
 
-# ---------------------------------------------------------------------------
-# Original control logic, preserved from the source example
-# ---------------------------------------------------------------------------
+# -------------
+# control logic
+# -------------
 
 { :input1 :measurement10 ?M1.
   :input2 :measurement2 true.
@@ -78,9 +77,9 @@
   ?M1 math:notLessThan ?M2.
 }.
 
-# ---------------------------------------------------------------------------
+# -------------------------------------------------------------------
 # Explanation layer: compute an explicit why-story from the raw facts
-# ---------------------------------------------------------------------------
+# -------------------------------------------------------------------
 
 { :input1 :measurement1 (?Low ?High).
   ?Low math:lessThan ?High.
@@ -134,9 +133,9 @@
             :actuator1Command ?A1;
             :actuator2Command ?A2. }.
 
-# ---------------------------------------------------------------------------
+# ----------
 # ARC report
-# ---------------------------------------------------------------------------
+# ----------
 
 { :decision :answer ?Answer;
             :actuator1Command ?A1;

package/examples/easter.n3

@@ -1,78 +1,208 @@
-# =====================================================================
-# Easter Date
-# Calculation of easter dates.
-# original copy at http://www.w3.org/2000/10/swap/test/easter/easter.n3
-# =====================================================================
-
-@prefix math: <http://www.w3.org/2000/10/swap/math#>.
-@prefix log: <http://www.w3.org/2000/10/swap/log#>.
-@prefix string: <http://www.w3.org/2000/10/swap/string#>.
-@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
-@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
-@prefix prolog: <http://eulersharp.sourceforge.net/2003/03swap/prolog#>.
-@prefix : <http://www.agfa.com/w3c/euler/easterP#>.
-
-<> rdfs:comment """
-              Divide            by      Quotient  Remainder
-        ---------------------------------------------------
-                 y               19                   j
-                 y              100        k          h
-                 k                4        m          n
-               k + 8             25        p
-             k - p + 1            3        q
-        19j + k - m - q + 15     30                   r
-                 h                4        s          u
-        32 + 2n + 2s - r - u      7                   v
-           j + 11r + 22v        451        w
-         r + v - 7w + 114        31        x          z
-
-Here x is the number of the month ond 1 + z is the day of that
-month upon which Easter Sunday falls in the year y.
-""".
-
-2021 a :Year.
-2022 a :Year.
-2023 a :Year.
-2024 a :Year.
-2025 a :Year.
-2026 a :Year.
-2027 a :Year.
-2028 a :Year.
-2029 a :Year.
-2030 a :Year.
-2031 a :Year.
-2032 a :Year.
-2033 a :Year.
-2034 a :Year.
-2035 a :Year.
-2036 a :Year.
-2037 a :Year.
-2038 a :Year.
-2039 a :Year.
-2040 a :Year.
-2041 a :Year.
-2042 a :Year.
-2043 a :Year.
-2044 a :Year.
-2045 a :Year.
-2046 a :Year.
-2047 a :Year.
-2048 a :Year.
-2049 a :Year.
-2050 a :Year.
-
-{   ?Y a :Year.
-    (?Y 19) math:remainder ?J.
-    (?Y 100) math:integerQuotient ?K; math:remainder ?H.
-    (?K 4) math:integerQuotient ?M; math:remainder ?N.
-    ((?K 8)!math:sum 25) math:integerQuotient ?P.
-    (((?K ?P)!math:difference 1)!math:sum 3) math:integerQuotient ?Q.
-    ((((((19 ?J)!math:product ?K)!math:sum ?M)!math:difference ?Q)!math:difference 15)!math:sum 30) math:remainder ?R.
-    (?H 4) math:integerQuotient ?S; math:remainder ?U.
-    ((32 (2 ?N)!math:product (2 ?S)!math:product ?R!math:negation ?U!math:negation)!math:sum 7) math:remainder ?V.
-    ((?J (11 ?R)!math:product (22 ?V)!math:product)!math:sum 451) math:integerQuotient ?W.
-    ((?R ?V (7 ?W)!math:product!math:negation 114)!math:sum 31) math:integerQuotient ?X; math:remainder ?Z.
-    (?Z 1) math:sum ?DAY.
-} => {
-    (?DAY ?X) :easterFor ?Y.
-}.
+# ==========================================================================
+# Easter — ARC-style
+#
+# This example computes the date of Easter Sunday in the Gregorian calendar.
+# For each year in a sample range, it applies the classic computus step by
+# step, explains the resulting month and day, and then checks independent
+# properties of the result: cycle bounds, remainder bounds, and the legal
+# Easter date window in March or April.
+# ==========================================================================
+
+@prefix : <https://example.org/easter-arc#> .
+@prefix math: <http://www.w3.org/2000/10/swap/math#> .
+@prefix log: <http://www.w3.org/2000/10/swap/log#> .
+@prefix string: <http://www.w3.org/2000/10/swap/string#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+<> rdfs:comment """This ARC-style version keeps the Gregorian computus from the original example and reports, for each sample year, an Answer, a Reason Why, and a set of independent Checks.""" .
+
+:y2026 a :Case; :year 2026 .
+:y2027 a :Case; :year 2027 .
+:y2028 a :Case; :year 2028 .
+:y2029 a :Case; :year 2029 .
+:y2030 a :Case; :year 2030 .
+:y2031 a :Case; :year 2031 .
+:y2032 a :Case; :year 2032 .
+:y2033 a :Case; :year 2033 .
+:y2034 a :Case; :year 2034 .
+:y2035 a :Case; :year 2035 .
+
+:goldenRemainder :value 0 .
+:goldenRemainder :value 1 .
+:goldenRemainder :value 2 .
+:goldenRemainder :value 3 .
+:goldenRemainder :value 4 .
+:goldenRemainder :value 5 .
+:goldenRemainder :value 6 .
+:goldenRemainder :value 7 .
+:goldenRemainder :value 8 .
+:goldenRemainder :value 9 .
+:goldenRemainder :value 10 .
+:goldenRemainder :value 11 .
+:goldenRemainder :value 12 .
+:goldenRemainder :value 13 .
+:goldenRemainder :value 14 .
+:goldenRemainder :value 15 .
+:goldenRemainder :value 16 .
+:goldenRemainder :value 17 .
+:goldenRemainder :value 18 .
+
+:epactRemainder :value 0 .
+:epactRemainder :value 1 .
+:epactRemainder :value 2 .
+:epactRemainder :value 3 .
+:epactRemainder :value 4 .
+:epactRemainder :value 5 .
+:epactRemainder :value 6 .
+:epactRemainder :value 7 .
+:epactRemainder :value 8 .
+:epactRemainder :value 9 .
+:epactRemainder :value 10 .
+:epactRemainder :value 11 .
+:epactRemainder :value 12 .
+:epactRemainder :value 13 .
+:epactRemainder :value 14 .
+:epactRemainder :value 15 .
+:epactRemainder :value 16 .
+:epactRemainder :value 17 .
+:epactRemainder :value 18 .
+:epactRemainder :value 19 .
+:epactRemainder :value 20 .
+:epactRemainder :value 21 .
+:epactRemainder :value 22 .
+:epactRemainder :value 23 .
+:epactRemainder :value 24 .
+:epactRemainder :value 25 .
+:epactRemainder :value 26 .
+:epactRemainder :value 27 .
+:epactRemainder :value 28 .
+:epactRemainder :value 29 .
+
+:weekdayRemainder :value 0 .
+:weekdayRemainder :value 1 .
+:weekdayRemainder :value 2 .
+:weekdayRemainder :value 3 .
+:weekdayRemainder :value 4 .
+:weekdayRemainder :value 5 .
+:weekdayRemainder :value 6 .
+
+:slot_m3_d22 :monthNum 3; :day 22 .
+:slot_m3_d23 :monthNum 3; :day 23 .
+:slot_m3_d24 :monthNum 3; :day 24 .
+:slot_m3_d25 :monthNum 3; :day 25 .
+:slot_m3_d26 :monthNum 3; :day 26 .
+:slot_m3_d27 :monthNum 3; :day 27 .
+:slot_m3_d28 :monthNum 3; :day 28 .
+:slot_m3_d29 :monthNum 3; :day 29 .
+:slot_m3_d30 :monthNum 3; :day 30 .
+:slot_m3_d31 :monthNum 3; :day 31 .
+:slot_m4_d1 :monthNum 4; :day 1 .
+:slot_m4_d2 :monthNum 4; :day 2 .
+:slot_m4_d3 :monthNum 4; :day 3 .
+:slot_m4_d4 :monthNum 4; :day 4 .
+:slot_m4_d5 :monthNum 4; :day 5 .
+:slot_m4_d6 :monthNum 4; :day 6 .
+:slot_m4_d7 :monthNum 4; :day 7 .
+:slot_m4_d8 :monthNum 4; :day 8 .
+:slot_m4_d9 :monthNum 4; :day 9 .
+:slot_m4_d10 :monthNum 4; :day 10 .
+:slot_m4_d11 :monthNum 4; :day 11 .
+:slot_m4_d12 :monthNum 4; :day 12 .
+:slot_m4_d13 :monthNum 4; :day 13 .
+:slot_m4_d14 :monthNum 4; :day 14 .
+:slot_m4_d15 :monthNum 4; :day 15 .
+:slot_m4_d16 :monthNum 4; :day 16 .
+:slot_m4_d17 :monthNum 4; :day 17 .
+:slot_m4_d18 :monthNum 4; :day 18 .
+:slot_m4_d19 :monthNum 4; :day 19 .
+:slot_m4_d20 :monthNum 4; :day 20 .
+:slot_m4_d21 :monthNum 4; :day 21 .
+:slot_m4_d22 :monthNum 4; :day 22 .
+:slot_m4_d23 :monthNum 4; :day 23 .
+:slot_m4_d24 :monthNum 4; :day 24 .
+:slot_m4_d25 :monthNum 4; :day 25 .
+
+# --------
+# Computus
+# --------
+
+{ ?Case a :Case; :year ?Y.
+  (?Y 19) math:remainder ?J.
+  (?Y 100) math:integerQuotient ?K; math:remainder ?H.
+  (?K 4) math:integerQuotient ?M; math:remainder ?N.
+  ((?K 8)!math:sum 25) math:integerQuotient ?P.
+  (((?K ?P)!math:difference 1)!math:sum 3) math:integerQuotient ?Q.
+  ((((((19 ?J)!math:product ?K)!math:sum ?M)!math:difference ?Q)!math:difference 15)!math:sum 30)
+      math:remainder ?R.
+  (?H 4) math:integerQuotient ?S; math:remainder ?U.
+  ((32 (2 ?N)!math:product (2 ?S)!math:product ?R!math:negation ?U!math:negation)!math:sum 7)
+      math:remainder ?V.
+  ((?J (11 ?R)!math:product (22 ?V)!math:product)!math:sum 451)
+      math:integerQuotient ?W.
+  ((?R ?V (7 ?W)!math:product!math:negation 114)!math:sum 31)
+      math:integerQuotient ?X; math:remainder ?Z.
+  (?Z 1) math:sum ?DAY.
+}
+=>
+{ ?Case
+    :j ?J;
+    :k ?K;
+    :h ?H;
+    :m ?M;
+    :n ?N;
+    :p ?P;
+    :q ?Q;
+    :r ?R;
+    :s ?S;
+    :u ?U;
+    :v ?V;
+    :w ?W;
+    :monthNum ?X;
+    :day ?DAY;
+    :z ?Z. } .
+
+{ ?Case :monthNum 3. } => { ?Case :monthName "March". } .
+{ ?Case :monthNum 4. } => { ?Case :monthName "April". } .
+
+# ------------------
+# Independent checks
+# ------------------
+
+{ ?Case :j ?J. :goldenRemainder :value ?J. }
+    => { ?Case :check1 "C1 OK - the Golden Number remainder j is inside the 0–18 cycle.\n" . } .
+
+{ ?Case :r ?R. :epactRemainder :value ?R. }
+    => { ?Case :check2 "C2 OK - the epact-style remainder r is inside the 0–29 cycle.\n" . } .
+
+{ ?Case :v ?V. :weekdayRemainder :value ?V. }
+    => { ?Case :check3 "C3 OK - the weekday adjustment v is inside the 0–6 cycle.\n" . } .
+
+{ ?Case :monthNum ?M; :monthName ?Name. }
+    => { ?Case :check4 "C4 OK - the final month is a valid Easter month (March or April).\n" . } .
+
+{ ?Case :monthNum ?M; :day ?D.
+  ?Slot :monthNum ?M; :day ?D. }
+    => { ?Case :check5 "C5 OK - the final date is inside the legal Gregorian Easter window.\n" . } .
+
+# ----------------
+# ARC-style report
+# ----------------
+
+{ ?Case :year ?Y; :monthName ?Month; :day ?Day;
+        :j ?J; :k ?K; :q ?Q; :r ?R; :v ?V; :monthNum ?X; :z ?Z;
+        :check1 ?C1; :check2 ?C2; :check3 ?C3; :check4 ?C4; :check5 ?C5.
+  (
+    "Easter — Gregorian computus\n\n"
+    "=== " ?Y " ===\n"
+    "Answer\n"
+    "Easter Sunday falls on " ?Month " " ?Day ".\n\n"
+    "Reason Why\n"
+    "For year " ?Y ", the computus gives j=" ?J ", k=" ?K ", q=" ?Q
+    ", r=" ?R ", v=" ?V ", and final month/day numbers x=" ?X ", z=" ?Z ". "
+    "Because the day is z+1, the resulting Easter date is " ?Month " " ?Day ".\n\n"
+    "Check\n"
+    ?C1 ?C2 ?C3 ?C4 ?C5
+  ) string:concatenation ?Block. }
+    =>
+{ :report log:outputString ?Block. } .