eyeling 1.15.3 → 1.15.4

package/HANDBOOK.md

@@ -561,6 +561,47 @@ Implementation notes:
 - Keys are _structural_. Atoms use stable IDs; lists use element keys; variables use their identity (so two different variables are **not** conflated). This keeps the cycle check conservative and avoids accidental pruning.
 - This is not full tabling: it does not memoize answers, it only guards against immediate cycles (the common “A depends on A” loops).
 
+### 8.4.1 Minimal completed-goal tabling
+
+Eyeling has a **very small, deliberately conservative answer table** for backward goals.
+
+What is cached:
+
+- only **completed** answer sets
+- keyed by the **fully substituted goal list**
+- only when the proof is entered from a “top-level” call shape (no active per-branch `visited` context)
+- only when the engine is not in a result-limiting mode such as `maxResults`
+
+What is **not** cached:
+
+- pending / in-progress goals
+- recursive dependency states
+- partial answer streams
+- branch-local states inside an active recursive proof
+
+This matters because exposing **pending** answers without dependency propagation would change the meaning of recursive programs. Eyeling therefore caches only results that are already complete and replays them only when the surrounding proof context is equivalent.
+
+The cache is invalidated whenever any of the following changes:
+
+- the number of known facts
+- the number of backward rules
+- the scoped-closure level
+- whether a frozen scoped snapshot is active
+
+So this is **not SLG tabling** and not a general recursion engine. It is best understood as a reuse optimization for repeated backward proofs in a stable proof environment.
+
+Typical win cases:
+
+- many repeated `log:query` directives with the **same premise**
+- repeated forward-rule body proofs that ask the same completed backward question
+- “query-like” workloads where the expensive part is a repeated backward proof and the fact store does not change between calls
+
+Typical non-win cases:
+
+- first-time proofs
+- recursive subgoals whose value depends on future answers
+- workloads where the fact set changes between almost every call
+
 ### 8.5 Backward rules: indexed by head predicate
 
 Backward rules are indexed in `backRules.__byHeadPred`. When proving a goal with IRI predicate `p`, Eyeling retrieves:
@@ -706,7 +747,7 @@ Forward chaining runs inside an _outer loop_ that alternates:
 
 This produces deterministic behavior for scoped operations: they observe a stable snapshot, not a moving target.
 
-**Implementation note (performance):** the two-phase scheme is only needed when the program actually uses scoped built-ins. If no rule contains `log:collectAllIn`, `log:forAllIn`, `log:includes`, or `log:notIncludes`, Eyeling now **skips Phase B entirely** and runs only a single saturation. This avoids re-running the forward fixpoint and can prevent a “query-like” forward rule (one whose body contains an expensive backward proof search) from being executed twice.
+**Implementation note (performance):** the two-phase scheme is only needed when the program actually uses scoped built-ins. If no rule contains `log:collectAllIn`, `log:forAllIn`, `log:includes`, or `log:notIncludes`, Eyeling **skips Phase B entirely** and runs only a single saturation. This avoids re-running the forward fixpoint and can prevent a “query-like” forward rule (one whose body contains an expensive backward proof search) from being executed twice.
 
 **Implementation note (performance):** in Phase A there is no snapshot, so scoped built-ins (and priority-gated scoped queries) are guaranteed to “delay” by failing.  
 Instead of proving the entire forward-rule body only to fail at the end, Eyeling precomputes whether a forward rule depends on scoped built-ins and skips it until a snapshot exists and the requested closure level is reached. This can avoid very expensive proof searches in programs that combine recursion with `log:*In` built-ins.
@@ -1379,6 +1420,8 @@ Each enumerated rule is standardized apart (fresh variable names) before unifica
 
 This is “forward-rule-like” in spirit (premise ⇒ conclusion), but the instantiated conclusion triples are **not added back into the fact store**; they are just what Eyeling prints.
 
+**Implementation note (performance):** repeated top-level `log:query` directives with the **same premise formula** are a good fit for Eyeling’s minimal completed-goal tabling (§8.4.1). The first query still performs the full backward proof; later identical premises can reuse the completed answer set as long as the saturated closure and scoped-query context are unchanged.
+
 **Important details:**
 
 - Only **top-level** `{...} log:query {...}.` directives are recognized. Inside quoted formulas (or inside rule bodies/heads) it is just an ordinary triple.
@@ -2448,7 +2491,7 @@ It runs against the external suite.
 
 That means:
 
-- the benchmark is shared
+- the compliance test suite is shared
 - the contract is public
 - the result is independently meaningful
 

package/examples/floating-point-first-ema-tracker.n3

@@ -0,0 +1,193 @@
+# ====================================================================================
+# Floating-point-first EMA tracking envelope
+#
+# Why this example exists:
+#   It is another floating-point-first certificate in the same family as the servo,
+#   RC-discharge, and thermal-cooling examples, but now phrased as an exponential
+#   moving average (EMA) tracker.
+#
+# Physical story:
+#   Let e(k) be the absolute tracking error of an EMA estimator relative to a constant
+#   target. Then
+#
+#       e(k+1) = a * e(k)
+#
+#   where a is the complement of the EMA gain. In this example we choose
+#
+#       a = exp(-Ts/tau) = exp(-1/6)
+#
+#   with Ts = 0.5 s and tau = 3 s.
+#
+#   Since exp(-1/6) is transcendental, we certify it by a double interval:
+#
+#       8.464817248e-1 <= exp(-1/6) <= 8.464817249e-1
+#
+#   and propagate a floating-point envelope for the tracking error.
+#
+# What is certified:
+#   * the double interval is nonempty and strictly below 1
+#   * the tracking-error envelope shrinks at every sample
+#   * from an initial error of 8.0e0, the estimator is guaranteed within 2.5e-1
+#     by sample 21
+#   * with Ts = 5.0e-1 s, that means guaranteed settling by 1.05e1 s
+# ====================================================================================
+
+@prefix :     <http://example.org/floating-ema#>.
+@prefix math: <http://www.w3.org/2000/10/swap/math#>.
+@prefix log:  <http://www.w3.org/2000/10/swap/log#>.
+
+# ----------
+# Parameters
+# ----------
+
+:ema a :SampledEMAEnvelope;
+  :samplePeriod 5.0e-1;
+  :timeConstant 3.0e0;
+  :exactDecaySymbol "exp(-1/6)";
+  :decayLower 8.464817248e-1;
+  :decayUpper 8.464817249e-1;
+  :initialAbsTrackingError 8.0e0;
+  :tolerance 2.5e-1;
+  :maxStep 24.
+
+# ----------------------------------------------------------------
+# The double interval is a finite certificate for a transcendental
+# ----------------------------------------------------------------
+
+{
+  :ema :decayLower ?lo.
+  :ema :decayUpper ?hi.
+  ?lo math:lessThan ?hi.
+  ?hi math:lessThan 1.0e0.
+  ?lo math:greaterThan 0.0e0.
+}
+=>
+{
+  :ema :decayCertificate :CertifiedDoubleInterval.
+  :ema :contractiveDecay true.
+}.
+
+# ----------------
+# Initial envelope
+# ----------------
+
+{
+  :ema :initialAbsTrackingError ?e0.
+}
+=>
+{
+  :ema :trackingErrorEnvelopeAt (0 ?e0 ?e0).
+}.
+
+# -------------------------------------
+# Envelope propagation
+#   lower(k+1) = decayLower * lower(k)
+#   upper(k+1) = decayUpper * upper(k)
+# -------------------------------------
+
+{
+  :ema :maxStep ?max;
+       :decayLower ?aLo;
+       :decayUpper ?aHi.
+  :ema :trackingErrorEnvelopeAt (?k ?lo ?hi).
+  ?k math:lessThan ?max.
+  ( ?k 1 ) math:sum ?k1.
+  ( ?aLo ?lo ) math:product ?lo1.
+  ( ?aHi ?hi ) math:product ?hi1.
+}
+=>
+{
+  :ema :trackingErrorEnvelopeAt (?k1 ?lo1 ?hi1).
+}.
+
+# -----------------------------
+# The envelope shrinks strictly
+# -----------------------------
+
+{
+  :ema :trackingErrorEnvelopeAt (?k ?lo ?hi).
+  ( ?k 1 ) math:sum ?k1.
+  :ema :trackingErrorEnvelopeAt (?k1 ?lo1 ?hi1).
+  ?hi1 math:lessThan ?hi.
+}
+=>
+{
+  :ema :strictContractionAt ?k.
+}.
+
+# --------------------------------
+# Settlement in the tolerance band
+# --------------------------------
+
+{
+  :ema :trackingErrorEnvelopeAt (?k ?lo ?hi).
+  :ema :tolerance ?tol.
+  ?hi math:lessThan ?tol.
+}
+=>
+{
+  :ema :settledCandidate ?k.
+}.
+
+{
+  :ema :settledCandidate ?k.
+  ?k math:greaterThan 0.
+  ( ?k 1 ) math:difference ?km1.
+  :ema :trackingErrorEnvelopeAt (?km1 ?prevLo ?prevHi).
+  :ema :tolerance ?tol.
+  ?prevHi math:notLessThan ?tol.
+}
+=>
+{
+  :ema :firstSettledStep ?k.
+}.
+
+{
+  :ema :firstSettledStep ?k.
+  :ema :samplePeriod ?ts.
+  ( ?k ?ts ) math:product ?t.
+}
+=>
+{
+  :ema :firstSettledTime ?t.
+}.
+
+# -----------------------------------------------------------
+# Readable engineering summary for the floating-point witness
+# -----------------------------------------------------------
+
+{
+  :ema :firstSettledStep ?k;
+       :firstSettledTime ?t;
+       :tolerance ?tol;
+       :exactDecaySymbol ?sym;
+       :decayLower ?aLo;
+       :decayUpper ?aHi.
+}
+log:query
+{
+  :result :summary (
+    "exact-decay" ?sym
+    "double-lower" ?aLo
+    "double-upper" ?aHi
+    "tolerance" ?tol
+    "first-settled-step" ?k
+    "first-settled-time-s" ?t
+  ).
+}.
+
+{
+  :ema :trackingErrorEnvelopeAt (?k ?lo ?hi).
+}
+log:query
+{
+  :result :envelope (?k ?lo ?hi).
+}.
+
+{
+  :ema :strictContractionAt ?k.
+}
+log:query
+{
+  :result :contractionAt ?k.
+}.

package/examples/floating-point-first-rc-discharge.n3

@@ -0,0 +1,190 @@
+# =======================================================================================
+# Floating-point-first RC discharge envelope
+#
+# Why this example exists:
+#   It is another floating-point-first certificate, parallel to the servo-envelope style,
+#   but framed as a passive RC discharge.
+#
+# Physical story:
+#   A sampled RC voltage obeys
+#
+#       v(k+1) = a * v(k)
+#
+#   with exact discrete decay factor
+#
+#       a = exp(-Ts/tau) = exp(-1/4)
+#
+#   for Ts = 25 ms and tau = 100 ms.
+#
+#   Because exp(-1/4) is transcendental, we certify it by a double interval:
+#
+#       7.788007830e-1 <= exp(-1/4) <= 7.788007831e-1
+#
+#   and propagate a floating-point envelope on the capacitor voltage.
+#
+# What is certified:
+#   * the double interval is nonempty and strictly below 1
+#   * the voltage envelope shrinks sample by sample
+#   * from an initial voltage of 2.40e1 V, the capacitor is guaranteed below 1.0e0 V
+#     by sample 15
+#   * with Ts = 2.5e-2 s, that means guaranteed settling by 3.75e-1 s
+# =======================================================================================
+
+@prefix :     <http://example.org/floating-rc#>.
+@prefix math: <http://www.w3.org/2000/10/swap/math#>.
+@prefix log:  <http://www.w3.org/2000/10/swap/log#>.
+
+# ----------
+# Parameters
+# ----------
+
+:rc a :SampledRCEnvelope;
+  :samplePeriod 2.5e-2;
+  :timeConstant 1.0e-1;
+  :exactDecaySymbol "exp(-1/4)";
+  :decayLower 7.788007830e-1;
+  :decayUpper 7.788007831e-1;
+  :initialVoltage 2.40e1;
+  :tolerance 1.0e0;
+  :maxStep 18.
+
+# ----------------------------------------------------------------
+# The double interval is a finite certificate for a transcendental
+# ----------------------------------------------------------------
+
+{
+  :rc :decayLower ?lo; :decayUpper ?hi.
+  ?lo math:lessThan ?hi.
+  ?hi math:lessThan 1.0e0.
+  ?lo math:greaterThan 0.0e0.
+}
+=>
+{
+  :rc :decayCertificate :CertifiedDoubleInterval.
+  :rc :contractiveDecay true.
+}.
+
+# ----------------
+# Initial envelope
+# ----------------
+
+{
+  :rc :initialVoltage ?v0.
+}
+=>
+{
+  :rc :voltageEnvelopeAt (0 ?v0 ?v0).
+}.
+
+# -------------------------------------
+# Envelope propagation
+#   lower(k+1) = decayLower * lower(k)
+#   upper(k+1) = decayUpper * upper(k)
+# -------------------------------------
+
+{
+  :rc :maxStep ?max;
+      :decayLower ?aLo;
+      :decayUpper ?aHi.
+  :rc :voltageEnvelopeAt (?k ?lo ?hi).
+  ?k math:lessThan ?max.
+  ( ?k 1 ) math:sum ?k1.
+  ( ?aLo ?lo ) math:product ?lo1.
+  ( ?aHi ?hi ) math:product ?hi1.
+}
+=>
+{
+  :rc :voltageEnvelopeAt (?k1 ?lo1 ?hi1).
+}.
+
+# -----------------------------
+# The envelope shrinks strictly
+# -----------------------------
+
+{
+  :rc :voltageEnvelopeAt (?k ?lo ?hi).
+  ( ?k 1 ) math:sum ?k1.
+  :rc :voltageEnvelopeAt (?k1 ?lo1 ?hi1).
+  ?hi1 math:lessThan ?hi.
+}
+=>
+{
+  :rc :strictContractionAt ?k.
+}.
+
+# --------------------------------
+# Settlement in the tolerance band
+# --------------------------------
+
+{
+  :rc :voltageEnvelopeAt (?k ?lo ?hi).
+  :rc :tolerance ?tol.
+  ?hi math:lessThan ?tol.
+}
+=>
+{
+  :rc :settledCandidate ?k.
+}.
+
+{
+  :rc :settledCandidate ?k.
+  ?k math:greaterThan 0.
+  ( ?k 1 ) math:difference ?km1.
+  :rc :voltageEnvelopeAt (?km1 ?prevLo ?prevHi).
+  :rc :tolerance ?tol.
+  ?prevHi math:notLessThan ?tol.
+}
+=>
+{
+  :rc :firstSettledStep ?k.
+}.
+
+{
+  :rc :firstSettledStep ?k.
+  :rc :samplePeriod ?ts.
+  ( ?k ?ts ) math:product ?t.
+}
+=>
+{
+  :rc :firstSettledTime ?t.
+}.
+
+# -----------------------------------------------------------
+# Readable engineering summary for the floating-point witness
+# -----------------------------------------------------------
+
+{
+  :rc :firstSettledStep ?k;
+      :firstSettledTime ?t;
+      :tolerance ?tol;
+      :exactDecaySymbol ?sym;
+      :decayLower ?aLo;
+      :decayUpper ?aHi.
+}
+log:query
+{
+  :result :summary (
+    "exact-decay" ?sym
+    "double-lower" ?aLo
+    "double-upper" ?aHi
+    "tolerance" ?tol
+    "first-settled-step" ?k
+    "first-settled-time-s" ?t
+  ).
+}.
+
+{
+  :rc :voltageEnvelopeAt (?k ?lo ?hi).
+}
+log:query
+{
+  :result :envelope (?k ?lo ?hi).
+}.
+
+{
+  :rc :strictContractionAt ?k.
+}
+log:query
+{
+  :result :contractionAt ?k.
+}.

package/examples/floating-point-first-servo-envelope.n3

@@ -0,0 +1,195 @@
+# =======================================================================================
+# Floating-point-first transcendental servo envelope
+#
+# Why this example exists:
+#   It complements the integer-first and decimal-first examples with a version whose
+#   certifying arithmetic starts from floating-point literals.
+#
+# Physical story:
+#   A sampled first-order servo has error dynamics
+#
+#       e(k+1) = a * e(k)
+#
+#   with exact discrete pole
+#
+#       a = exp(-Ts/tau) = exp(-1/3)
+#
+#   for Ts = 20 ms and tau = 60 ms.
+#
+#   The number exp(-1/3) is transcendental, so it is not available as a finite exact
+#   decimal or rational. In this example we work floating-point-first: the certificate is
+#   carried by N3 double literals, written in exponent form.
+#
+# Floating-point-first move:
+#   We store a certified double interval
+#
+#       7.165313105e-1 <= exp(-1/3) <= 7.165313106e-1
+#
+#   and propagate a double error envelope. The resulting derivations stay explicit and
+#   machine-checkable, but now the numeric layer is “floating-point first”.
+#
+# What is certified:
+#   * the double interval is nonempty and contractive
+#   * the error envelope shrinks at every sample
+#   * from an initial error of 1.25e1, the loop is guaranteed inside 5.0e-1 by sample 10
+#   * with Ts = 2.0e-2 s, that means guaranteed settling by 2.0e-1 s
+# =======================================================================================
+
+@prefix :     <http://example.org/floating-servo#>.
+@prefix math: <http://www.w3.org/2000/10/swap/math#>.
+@prefix log:  <http://www.w3.org/2000/10/swap/log#>.
+
+# ----------
+# Parameters
+# ----------
+
+:servo a :SampledServoEnvelope;
+  :samplePeriod 2.0e-2;
+  :timeConstant 6.0e-2;
+  :exactPoleSymbol "exp(-1/3)";
+  :poleLower 7.165313105e-1;
+  :poleUpper 7.165313106e-1;
+  :initialAbsError 1.25e1;
+  :tolerance 5.0e-1;
+  :maxStep 12.
+
+# ----------------------------------------------------------------
+# The double interval is a finite certificate for a transcendental
+# ----------------------------------------------------------------
+
+{
+  :servo :poleLower ?lo; :poleUpper ?hi.
+  ?lo math:lessThan ?hi.
+  ?hi math:lessThan 1.0e0.
+  ?lo math:greaterThan 0.0e0.
+}
+=>
+{
+  :servo :poleCertificate :CertifiedDoubleInterval.
+  :servo :contractivePole true.
+}.
+
+# ----------------
+# Initial envelope
+# ----------------
+
+{
+  :servo :initialAbsError ?e0.
+}
+=>
+{
+  :servo :errorEnvelopeAt (0 ?e0 ?e0).
+}.
+
+# -----------------------------------
+# Envelope propagation
+#   lower(k+1) = poleLower * lower(k)
+#   upper(k+1) = poleUpper * upper(k)
+# -----------------------------------
+
+{
+  :servo :maxStep ?max;
+         :poleLower ?aLo;
+         :poleUpper ?aHi.
+  :servo :errorEnvelopeAt (?k ?lo ?hi).
+  ?k math:lessThan ?max.
+  ( ?k 1 ) math:sum ?k1.
+  ( ?aLo ?lo ) math:product ?lo1.
+  ( ?aHi ?hi ) math:product ?hi1.
+}
+=>
+{
+  :servo :errorEnvelopeAt (?k1 ?lo1 ?hi1).
+}.
+
+# -----------------------------
+# The envelope shrinks strictly
+# -----------------------------
+
+{
+  :servo :errorEnvelopeAt (?k ?lo ?hi).
+  ( ?k 1 ) math:sum ?k1.
+  :servo :errorEnvelopeAt (?k1 ?lo1 ?hi1).
+  ?hi1 math:lessThan ?hi.
+}
+=>
+{
+  :servo :strictContractionAt ?k.
+}.
+
+# --------------------------------
+# Settlement in the tolerance band
+# --------------------------------
+
+{
+  :servo :errorEnvelopeAt (?k ?lo ?hi).
+  :servo :tolerance ?tol.
+  ?hi math:lessThan ?tol.
+}
+=>
+{
+  :servo :settledCandidate ?k.
+}.
+
+{
+  :servo :settledCandidate ?k.
+  ?k math:greaterThan 0.
+  ( ?k 1 ) math:difference ?km1.
+  :servo :errorEnvelopeAt (?km1 ?prevLo ?prevHi).
+  :servo :tolerance ?tol.
+  ?prevHi math:notLessThan ?tol.
+}
+=>
+{
+  :servo :firstSettledStep ?k.
+}.
+
+{
+  :servo :firstSettledStep ?k.
+  :servo :samplePeriod ?ts.
+  ( ?k ?ts ) math:product ?t.
+}
+=>
+{
+  :servo :firstSettledTime ?t.
+}.
+
+# ---------------------------------------------------------------
+# Readable engineering summary for the floating-point certificate
+# ---------------------------------------------------------------
+
+{
+  :servo :firstSettledStep ?k;
+         :firstSettledTime ?t;
+         :tolerance ?tol;
+         :exactPoleSymbol ?sym;
+         :poleLower ?aLo;
+         :poleUpper ?aHi.
+}
+log:query
+{
+  :result :summary (
+    "exact-pole" ?sym
+    "double-lower" ?aLo
+    "double-upper" ?aHi
+    "tolerance" ?tol
+    "first-settled-step" ?k
+    "first-settled-time-s" ?t
+  ).
+}.
+
+{
+  :servo :errorEnvelopeAt (?k ?lo ?hi).
+}
+log:query
+{
+  :result :envelope (?k ?lo ?hi).
+}.
+
+{
+  :servo :strictContractionAt ?k.
+}
+log:query
+{
+  :result :contractionAt ?k.
+}.