eyeling 1.15.2 → 1.15.4

package/HANDBOOK.md

@@ -29,6 +29,7 @@
 - [Appendix B — Notation3: when facts can carry their own logic](#app-b)
 - [Appendix C — N3 beyond Prolog: logic that survives the open web](#app-c)
 - [Appendix D — LLM + Eyeling: A Repeatable Logic Toolchain](#app-d)
+- [Appendix E — How Eyeling reaches 100% on `notation3tests`](#app-e)
 
 ---
 
@@ -560,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:
@@ -705,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.
@@ -1378,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.
@@ -2160,3 +2204,347 @@ A simple structure that keeps the LLM honest:
 - “If something is unknown, emit a placeholder fact (`:needsFact`) rather than guessing.”
 
 The point isn’t that the LLM is “right”; it’s that **Eyeling makes the result checkable**, and the artifact becomes a maintainable program rather than a one-off generation.
+
+---
+
+<a id="app-e"></a>
+
+## Appendix E — How Eyeling reaches 100% on `notation3tests`
+
+### E.1 The goal
+
+Eyeling does not treat [notation3tests](https://codeberg.org/phochste/notation3tests/) as a side check.
+
+It treats the suite as an **external semantic contract**.
+
+That means:
+
+- the target is public
+- the target is reproducible
+- the target is outside the local codebase
+- success means interoperability, not self-consistency
+
+---
+
+### E.2 The test loop
+
+The workflow is simple and strict:
+
+- clone the external [notation3tests](https://codeberg.org/phochste/notation3tests/) suite
+- package the current Eyeling tree
+- install that package into the suite
+- run the suite’s Eyeling target
+- fix semantics, not cosmetics
+
+This keeps the suite honest and keeps Eyeling honest.
+
+---
+
+### E.3 The prompt packet
+
+A typical conformance-fix prompt is not open-ended.
+
+It usually includes a small, repeatable packet:
+
+- the Eyeling source as an attached zip `https://github.com/eyereasoner/eyeling/archive/refs/heads/main.zip`
+- pointers to the failing tests
+- the exact failing output, or the exact command needed to reproduce it
+- a pointer to the N3 spec `https://w3c.github.io/N3/spec/`
+- a pointer to the builtin definitions `https://w3c.github.io/N3/spec/builtins.html`
+- a direct request to fix the issue in the engine
+- a direct request to update `HANDBOOK.md`
+
+The request is usually phrased in a narrow way:
+
+- fix this specific failing conformance case
+- preserve existing passing behavior
+- make the smallest coherent patch
+- add or update a regression test if needed
+- update the handbook so the semantic rule is documented, not just implemented
+- do not stop at making the test green; align the implementation with the spec and explain the semantic reason in `HANDBOOK.md`
+
+The model is not asked to “improve the reasoner” in general.
+
+It is asked to repair one semantic gap against: the code, the failing test, the spec, and the handbook.
+
+---
+
+### E.4 The core idea
+
+Eyeling reaches 100% by making the engine match the semantics that the suite exercises.
+
+That means getting these right:
+
+- N3 syntax
+- rule forms
+- quoted formulas
+- variable and blank-node behavior
+- builtin relations
+- closure and duplicate control
+
+The result is not “test gaming.”
+
+The result is semantic alignment.
+
+---
+
+### E.5 One rule core, many surfaces
+
+The suite uses different surface forms for the same logical ideas.
+
+Eyeling accepts and normalizes them into one internal rule model:
+
+- `{ P } => { C } .`
+- `{ H } <= { B } .`
+- top-level `log:implies`
+- top-level `log:impliedBy`
+
+That matters because conformance depends on recognizing equivalence across syntax, not just parsing one preferred style.
+
+---
+
+### E.6 Normalize first, reason second
+
+A large share of conformance work happens **before** execution.
+
+Eyeling normalizes the tricky parts early:
+
+- body blanks become variables
+- head blanks stay existential
+- RDF collection encodings become list terms
+- rule syntax variants become one rule representation
+
+This removes ambiguity before the engine starts proving anything.
+
+---
+
+### E.7 Body blanks vs. head blanks
+
+This is one of the decisive details.
+
+In Eyeling:
+
+- blanks in rule bodies act like placeholders
+- blanks in rule heads act like fresh existentials
+
+That split is essential.
+
+Without it:
+
+- rule matching goes wrong
+- proofs become unstable
+- existential output becomes noisy
+- conformance drops
+
+---
+
+### E.8 Builtins must behave like relations
+
+Eyeling does not treat builtins as one-way helper functions.
+
+It treats them as **relations inside proof search**.
+
+That means a builtin can:
+
+- succeed
+- fail
+- bind variables
+- stay satisfiable without yet binding anything
+
+This is critical for the suite, because many builtin cases are really tests of search behavior, not just value computation.
+
+---
+
+### E.9 Delay builtins when needed
+
+Some builtins only become useful after neighboring goals bind enough variables.
+
+Eyeling handles that by deferring non-informative builtins inside conjunctions.
+
+So instead of failing too early, the engine:
+
+- rotates the builtin later
+- keeps proving the remaining goals
+- retries once more information exists
+
+This preserves logical behavior while staying operationally efficient.
+
+---
+
+### E.10 Formulas are first-class terms
+
+Quoted formulas are not treated as strings.
+
+They are treated as structured logical objects.
+
+That gives Eyeling the machinery it needs for:
+
+- formula matching
+- nested reasoning
+- `log:includes`
+- `log:conclusion`
+- formula comparison by alpha-equivalence
+
+This is a major reason the higher-level N3 tests pass cleanly.
+
+---
+
+### E.11 Alpha-equivalence matters
+
+Two formulas that differ only in internal names must still count as the same formula when their structure matches.
+
+Eyeling therefore compares formulas by structure, not by accidental naming.
+
+That removes a common source of false mismatches in:
+
+- quoted formulas
+- nested graphs
+- rule introspection
+- scoped reasoning
+
+---
+
+### E.12 Lists must have one meaning
+
+The suite exercises list behavior in more than one spelling.
+
+Eyeling unifies them:
+
+- concrete N3 lists
+- RDF `first/rest` collection encodings
+
+By materializing anonymous RDF collections into list terms, Eyeling gives both forms one semantic path through the engine.
+
+That keeps list reasoning consistent across the whole suite.
+
+---
+
+### E.13 Existentials must be stable
+
+A rule head with blanks must not generate endless fresh variants of the same logical result.
+
+Eyeling stabilizes this by skolemizing head blanks per firing instance.
+
+So one logical firing yields:
+
+- one stable witness
+- one stable derived shape
+- one meaningful duplicate check
+
+This is what lets closure reach a real fixpoint.
+
+---
+
+### E.14 Duplicate suppression is semantic, not cosmetic
+
+The engine does not merely try to avoid repeated printing.
+
+It tries to avoid repeated derivation of the same fact.
+
+That requires:
+
+- stable term ids
+- indexed fact storage
+- reliable duplicate keys
+- stable existential handling
+
+Without that, a reasoner can look busy forever and still fail conformance.
+
+---
+
+### E.15 Closure must really close
+
+Full conformance depends on real saturation behavior.
+
+Eyeling therefore treats closure as:
+
+- repeated rule firing
+- repeated proof over indexed facts
+- duplicate-aware insertion
+- termination at fixpoint
+
+This is what turns the engine from a parser plus demos into a conformance-grade reasoner.
+
+---
+
+### E.16 Performance choices support correctness
+
+Several implementation choices are operational, but they directly protect conformance:
+
+- predicate-based indexing
+- subject/object refinement
+- smallest-bucket candidate selection
+- fast duplicate keys
+- skipping already-known ground heads
+
+These choices reduce accidental nontermination and prevent operational noise from becoming semantic failure.
+
+---
+
+### E.17 The suite stays external
+
+This is a key discipline.
+
+Eyeling does not define success by a private in-repo imitation of [notation3tests](https://codeberg.org/phochste/notation3tests/).
+
+It runs against the external suite.
+
+That means:
+
+- the compliance test suite is shared
+- the contract is public
+- the result is independently meaningful
+
+A green run says something real.
+
+---
+
+### E.18 Every failure becomes an invariant
+
+Eyeling reaches 100% because failures are not patched superficially.
+
+Each failure is turned into an engine rule.
+
+Examples:
+
+- parser failure → broader syntax support
+- list failure → one unified list model
+- formula failure → alpha-equivalence discipline
+- builtin failure → relational evaluation
+- closure failure → stable existential handling
+
+That is how the suite shapes the engine.
+
+---
+
+### E.19 Why 100% happens
+
+Eyeling gets to 100% because all the key layers line up:
+
+- the parser accepts the full rule surface
+- normalization removes semantic ambiguity
+- formulas are real terms
+- builtins participate in proof search
+- existential output is stable
+- closure reaches a true fixpoint
+- the public suite remains the judge
+
+Once those pieces are in place, 100% is the visible result of a coherent design.
+
+---
+
+### E.20 Final takeaway
+
+Eyeling reaches full [notation3tests](https://codeberg.org/phochste/notation3tests/) conformance by making “pass the suite” and “implement N3 correctly enough to interoperate” the same task.
+
+That is the method:
+
+- external suite
+- one semantic core
+- early normalization
+- relational builtins
+- formula-aware reasoning
+- stable existential output
+- duplicate-safe fixpoint closure
+
+That is why the result is 100%.

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.
+}.