eyeling 1.14.0 → 1.14.1

package/HANDBOOK.md

@@ -1551,6 +1551,12 @@ If `i` is out of range, `out` is the original string.
 
 Returns the number of differing positions between `a` and `b`. Fails if the two strings have different lengths.
 
+#### `string:mutateSelectBest`
+
+**Shape:** `( samples current target mutProb seedState ) string:mutateSelectBest ( best bestScore seedState2 )`
+
+Generates `samples` mutated variants of `current` (mutating each character with probability `mutProb` percent), scores each candidate against `target` (Hamming distance), and returns the best candidate (lowest score). RNG is a deterministic 31-bit LCG, threaded via `seedState` → `seedState2`, so runs are reproducible.
+
 ### Containment and prefix/suffix tests
 
 - `string:contains`
@@ -1976,24 +1982,6 @@ References:
 
 If you are running untrusted inputs, consider `--super-restricted` to disable all builtins except implication.
 
-### Eyeling fast-path builtins
-
-Eyeling ships one optional fast-path builtins builtin e.g. used by the genetic-algorithm example:
-
-#### `urn:eyeling:ga:solveString`
-
-**Shape:** `( target mutationProbability samples seed traceEvery maxGenerations ) urn:eyeling:ga:solveString ( generation score value seed )`
-
-- `target` and `value` are `xsd:string` literals.
-- `mutationProbability` is interpreted as a percentage per character (0–100).
-- `traceEvery` controls debug tracing:
-  - `0` disables tracing,
-  - `1` traces every generation,
-  - `N` traces every `N` generations.
-- `maxGenerations` is a safety cap:
-  - `0` means unlimited,
-  - otherwise the builtin stops once `generation >= maxGenerations` (even if not solved).
-
 ### A.6 Skolemization and `log:skolem`
 
 When forward rule heads contain blank nodes (existentials), Eyeling replaces them with generated Skolem IRIs so derived facts are ground.

package/examples/genetic-algorithm.n3

@@ -10,46 +10,158 @@
 # This is a simple hill-climbing GA (selection + mutation, no crossover), using a seeded RNG
 # so runs are reproducible.
 #
-# Uses Eyeling's builtin:
-#   urn:eyeling:ga:solveString
+# The GA is still expressed as backward rules (<=) for the outer evolution loop,
+# but the expensive inner loop ("take N mutated samples and keep the best") is
+# handled by a single string builtin to avoid huge proof trees and OOM.
 #
-# Configure:
-#   :mutationProbability 5   # percent per character
-#   :samples 80
-#   :seed 100
-#   :traceEvery 0            # 0=off, 1=every generation, 100=every 100 generations
-#   :maxGenerations 0        # 0=unlimited
 # ==========================================================================================
 
-@prefix :       <http://example.org/ga-solve#>.
-@prefix ega:    <urn:eyeling:ga:>.
+@prefix :       <urn:ga:>.
 @prefix log:    <http://www.w3.org/2000/10/swap/log#>.
+@prefix math:   <http://www.w3.org/2000/10/swap/math#>.
+@prefix list:   <http://www.w3.org/2000/10/swap/list#>.
 @prefix string: <http://www.w3.org/2000/10/swap/string#>.
 
 :cfg
   :mutationProbability 5;
   :samples 80;
   :seed 100;
-  :traceEvery 1;
-  :maxGenerations 0.
 
-# solveResult(TargetString) = (generation score value seed)
-{ ?TargetString :solveResult ( ?Gen ?Score ?Value ?Seed ) } <= {
+  # Debug knobs:
+  :traceEvery 1;        # 0 disables; 1 traces every generation
+  :maxGenerations 0;    # 0 means unlimited
+
+  :alphabet (" " "A" "B" "C" "D" "E" "F" "G" "H" "I" "J" "K" "L" "M"
+             "N" "O" "P" "Q" "R" "S" "T" "U" "V" "W" "X" "Y" "Z").
+
+# ------------------------
+# Small arithmetic helpers
+# ------------------------
+
+{ ( ?N 1 ) :dec ?N1 } <= { ( ?N 1 ) math:difference ?N1 }.
+{ ( ?N 1 ) :inc ?N1 } <= { ( ?N 1 ) math:sum ?N1 }.
+
+# ----------------------------------------------
+# Seeded RNG (LCG) and JS Math.round(rnd() * N)
+# (Used only for the initial random chromosome.)
+# ----------------------------------------------
+
+{ ?S0 :lcgNext ?S1 } <= {
+  ( ?S0 1103515245 ) math:product ?P .
+  ( ?P 12345 ) math:sum ?T .
+  ( ?T 2147483648 ) math:remainder ?S1
+}.
+
+{ ( ?S0 ?N ) :randRound ( ?R ?S1 ) } <= {
+  ?S0 :lcgNext ?S1 .
+  ( ?S1 ?N ) math:product ?A .
+  ( ?A ?A ) math:sum ?TwoA .
+  ( ?TwoA 2147483648 ) math:sum ?Num .
+  ( 2147483648 2 ) math:product ?Den .
+  ( ?Num ?Den ) math:integerQuotient ?R
+}.
+
+{ ?S0 :randomAlpha ( ?Ch ?S1 ) } <= {
+  :cfg :alphabet ?Alphabet .
+  ( ?S0 26 ) :randRound ( ?Idx ?S1 ) .
+  ( ?Alphabet ?Idx ) list:memberAt ?Ch
+}.
+
+{ ( 0 ?S0 ) :randomText ( "" ?S0 ) } <= true.
+
+{ ( ?Len ?S0 ) :randomText ( ?Out ?S2 ) } <= {
+  ?Len math:greaterThan 0 .
+  ( ?Len 1 ) :dec ?Len1 .
+  ?S0 :randomAlpha ( ?Ch ?S1 ) .
+  ( ?Len1 ?S1 ) :randomText ( ?Rest ?S2 ) .
+  ( "%s%s" ?Ch ?Rest ) string:format ?Out
+}.
+
+# -------------------------
+# tracing helper (optional)
+# -------------------------
+
+{ ( 0 ?Gen ?Score ?Value ) :traceMaybe true } <= true.
+
+{ ( ?Every ?Gen ?Score ?Value ) :traceMaybe true } <= {
+  ?Every math:greaterThan 0 .
+  ( ?Gen ?Every ) math:remainder ?R .
+  ?R math:equalTo 0 .
+  ?Gen log:trace ( ?Score ?Value )
+}.
+
+# --------------
+# evolution loop
+# --------------
+
+# Stop when score == 0
+{ ( ?Current 0 ?Target ?MutProb ?Samples ?Gen ?S0 ?MaxGen ?TraceEvery )
+    :evolve ( ?Current ?Gen ?S0 ) } <= true.
+
+# Stop when generation cap is reached (only if MaxGen > 0)
+{ ( ?Current ?Score ?Target ?MutProb ?Samples ?Gen ?S0 ?MaxGen ?TraceEvery )
+    :evolve ( ?Current ?Gen ?S0 ) } <= {
+  ?Score math:notEqualTo 0 .
+  ?MaxGen math:greaterThan 0 .
+  ?Gen math:equalTo ?MaxGen
+}.
+
+# Unlimited run (MaxGen == 0): keep evolving
+{ ( ?Current ?Score ?Target ?MutProb ?Samples ?Gen ?S0 0 ?TraceEvery )
+    :evolve ( ?Final ?FinalGen ?S2 ) } <= {
+  ?Score math:notEqualTo 0 .
+  ( ?Samples ?Current ?Target ?MutProb ?S0 )
+    string:mutateSelectBest
+  ( ?Best ?BestScore ?S1 ) .
+  ( ?Gen 1 ) :inc ?Gen1 .
+  ( ?TraceEvery ?Gen1 ?BestScore ?Best ) :traceMaybe true .
+  ( ?Best ?BestScore ?Target ?MutProb ?Samples ?Gen1 ?S1 0 ?TraceEvery )
+    :evolve ( ?Final ?FinalGen ?S2 )
+}.
+
+# Bounded run (MaxGen > 0): keep evolving while Gen < MaxGen
+{ ( ?Current ?Score ?Target ?MutProb ?Samples ?Gen ?S0 ?MaxGen ?TraceEvery )
+    :evolve ( ?Final ?FinalGen ?S2 ) } <= {
+  ?Score math:notEqualTo 0 .
+  ?MaxGen math:greaterThan 0 .
+  ?Gen math:lessThan ?MaxGen .
+  ( ?Samples ?Current ?Target ?MutProb ?S0 )
+    string:mutateSelectBest
+  ( ?Best ?BestScore ?S1 ) .
+  ( ?Gen 1 ) :inc ?Gen1 .
+  ( ?TraceEvery ?Gen1 ?BestScore ?Best ) :traceMaybe true .
+  ( ?Best ?BestScore ?Target ?MutProb ?Samples ?Gen1 ?S1 ?MaxGen ?TraceEvery )
+    :evolve ( ?Final ?FinalGen ?S2 )
+}.
+
+# ----------------------------------
+# Public solver wrapper (string API)
+# ----------------------------------
+
+{ ?TargetString :solveResult ( ?Gen 0 ?Value ?Seed ) } <= {
   :cfg :mutationProbability ?MutProb;
        :samples ?Samples;
        :seed ?Seed;
        :traceEvery ?TraceEvery;
-       :maxGenerations ?MaxG.
+       :maxGenerations ?MaxGen.
+
+  ?TargetString string:length ?Len .
+
+  ( ?Len ?Seed ) :randomText ( ?Current0 ?S1 ) .
+
+  # initial score using string:hammingDistance
+  ( ?Current0 ?TargetString ) string:hammingDistance ?Score0 .
 
-  ( ?TargetString ?MutProb ?Samples ?Seed ?TraceEvery ?MaxG )
-    ega:solveString
-  ( ?Gen ?Score ?Value ?SeedOut ) .
+  ( ?Current0 ?Score0 ?TargetString ?MutProb ?Samples 0 ?S1 ?MaxGen ?TraceEvery )
+    :evolve
+  ( ?Value ?Gen ?S2 ) .
 
-  # By design, the 4th output is the (input) seed.
-  ?SeedOut log:equalTo ?Seed
+  # Succeeds only when solved:
+  ( ?Value ?TargetString ) string:hammingDistance 0 .
+  ?Value log:equalTo ?TargetString .
+  ?S2 log:equalTo ?_FinalSeedState
 }.
 
-# Boolean-ish API for querying success
 { ?TargetString :solved true } <= {
   ?TargetString :solveResult ( ?Gen 0 ?TargetString ?Seed )
 }.
@@ -60,4 +172,6 @@
 
 { "METHINKS IT IS LIKE A WEASEL" :solved true .
   ( "solve('%s').\n" "METHINKS IT IS LIKE A WEASEL" ) string:format ?Line
-} => { 1 log:outputString ?Line }.
+}
+log:query
+{ 1 log:outputString ?Line }.

package/eyeling-builtins.ttl

@@ -346,7 +346,5 @@ string:setCharAt a ex:Builtin ; ex:kind ex:Function ;
 string:hammingDistance a ex:Builtin ; ex:kind ex:Function ;
   rdfs:comment "Function: subject is a 2-item list (a b). Binds/unifies object with the number of differing positions (Hamming distance). Fails if lengths differ." .
 
-# --- eyeling fast path builtins ------------------------------
-
-ega:solveString a ex:Builtin ; ex:kind ex:Function ;
-  rdfs:comment "Eyeling extension: GA solver on strings. Subject list: (target mutationProbability samples seed traceEvery maxGenerations). Object list: (generation score value seed). traceEvery=0 disables tracing; maxGenerations=0 means unlimited." .
+string:mutateSelectBest a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Shape: (samples current target mutProb seedState) string:mutateSelectBest (best bestScore seedState2). Generates samples mutated variants of current (mutating each character with probability mutProb percent), scores each candidate against target (Hamming distance), and returns the best candidate (lowest score). RNG is a deterministic 31-bit LCG, threaded via seedState → seedState2, so runs are reproducible." .

package/eyeling.js

@@ -3547,34 +3547,35 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
     return s2 !== null ? [s2] : [];
   }
 
-  // -----------------------------------------------------------------
-  // 4.6.2 urn:eyeling:ga: builtins (fast GA on *strings*)
-  // -----------------------------------------------------------------
-
-  // urn:eyeling:ga:solveString
-  // Schema: ( $target $mutProb $samples $seed $traceEvery $maxGenerations ) :solveString ( $gen $score $value $seed )
-  // Side effect: if traceEvery > 0, prints: <gen> TRACE (<score> "<value>")
-  if (pv === 'urn:eyeling:ga:solveString') {
-    if (!(g.s instanceof ListTerm) || g.s.elems.length != 6) return [];
-
-    const target = termToJsXsdStringNoLang(g.s.elems[0]);
-    const mutProbNum = parseNum(g.s.elems[1]);
-    const samplesNum = parseNum(g.s.elems[2]);
-    const seedNum = parseNum(g.s.elems[3]);
-    const traceEveryNum = parseNum(g.s.elems[4]);
-    const maxGenNum = parseNum(g.s.elems[5]);
-
-    if (target === null || mutProbNum === null || samplesNum === null || seedNum === null) return [];
-    if (traceEveryNum === null || maxGenNum === null) return [];
+  // string:mutateSelectBest
+  // Schema:
+  //   ( $samples $current $target $mutProb $seedState )
+  //     string:mutateSelectBest
+  //   ( $best $bestScore $seedState2 )
+  //
+  // Deterministic 31-bit LCG (same as the GA demo):
+  //   state = (1103515245 * state + 12345) % 2^31
+  // and randRound(N) = Math.round((state/2^31) * N) with state advanced once per draw.
+  //
+  // This builtin exists to keep GA-style "many samples × many characters" loops out of
+  // the proof search (dramatically reducing memory use).
+  if (pv === STRING_NS + 'mutateSelectBest') {
+    if (!(g.s instanceof ListTerm) || g.s.elems.length !== 5) return [];
+
+    const samplesNum = parseNum(g.s.elems[0]);
+    const current = termToJsXsdStringNoLang(g.s.elems[1]);
+    const target = termToJsXsdStringNoLang(g.s.elems[2]);
+    const mutProbNum = parseNum(g.s.elems[3]);
+    const seedNum = parseNum(g.s.elems[4]);
+
+    if (samplesNum === null || current === null || target === null || mutProbNum === null || seedNum === null)
+      return [];
+    if (current.length !== target.length) return [];
 
-    const mutProb = Math.max(0, Math.trunc(mutProbNum));
     const samples = Math.max(1, Math.trunc(samplesNum));
+    const mutProb = Math.max(0, Math.trunc(mutProbNum));
     const seed0 = Math.trunc(seedNum);
 
-    const traceEvery = Math.max(0, Math.trunc(traceEveryNum));
-    const maxGenerations = Math.max(0, Math.trunc(maxGenNum));
-
-    // Deterministic 31-bit LCG using BigInt arithmetic (matches the N3 version)
     let state = BigInt(seed0);
     const MOD = 2147483648n; // 2^31
     const A = 1103515245n;
@@ -3594,12 +3595,6 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
       return p === 0 ? ' ' : String.fromCharCode(64 + p);
     }
 
-    function randomText(len) {
-      let out = '';
-      for (let i = 0; i < len; i++) out += randomAlpha();
-      return out;
-    }
-
     function mutate(str) {
       let out = '';
       for (let i = 0; i < str.length; i++) {
@@ -3616,50 +3611,22 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
       return diffs;
     }
 
-    const pref = trace.getTracePrefixes() || PrefixEnv.newDefault();
-    function doTrace(gen, sc, val) {
-      const genLit = internLiteral(String(gen));
-      const scLit = internLiteral(String(sc));
-      const valLit = makeStringLiteral(val);
-      const obj = new ListTerm([scLit, valLit]);
-      const xStr = termToN3(genLit, pref);
-      const yStr = termToN3(obj, pref);
-      trace.writeTraceLine(`${xStr} TRACE ${yStr}`);
-    }
-
-    let generation = 0;
-    let current = randomText(target.length);
-    let currentScore = score(current);
-
-    if (traceEvery > 0 && generation % traceEvery === 0) doTrace(generation, currentScore, current);
-
-    while (currentScore !== 0) {
-      if (maxGenerations > 0 && generation >= maxGenerations) break;
-
-      let best = '';
-      let bestScore = Infinity;
-
-      for (let i = 0; i < samples; i++) {
-        const cand = mutate(current);
-        const candScore = score(cand);
-        if (candScore < bestScore) {
-          best = cand;
-          bestScore = candScore;
-        }
-      }
+    let best = '';
+    let bestScore = Infinity;
 
-      generation += 1;
-      current = best;
-      currentScore = bestScore;
-
-      if (traceEvery > 0 && generation % traceEvery === 0) doTrace(generation, currentScore, current);
+    for (let i = 0; i < samples; i++) {
+      const cand = mutate(current);
+      const candScore = score(cand);
+      if (candScore < bestScore) {
+        best = cand;
+        bestScore = candScore;
+      }
     }
 
     const outList = new ListTerm([
-      internLiteral(String(generation)),
-      internLiteral(String(currentScore)),
-      makeStringLiteral(current),
-      internLiteral(String(seed0)),
+      makeStringLiteral(best),
+      internLiteral(String(bestScore)),
+      internLiteral(state.toString()),
     ]);
 
     const s2 = unifyTerm(g.o, outList, subst);
@@ -3686,11 +3653,6 @@ function isBuiltinPred(p) {
     return true;
   }
 
-  // Eyeling extension: GA demo builtins
-  if (v === 'urn:eyeling:ga:solveString') {
-    return true;
-  }
-
   return (
     v.startsWith(CRYPTO_NS) ||
     v.startsWith(MATH_NS) ||

package/lib/builtins.js

@@ -3535,34 +3535,32 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
     return s2 !== null ? [s2] : [];
   }
 
-  // -----------------------------------------------------------------
-  // 4.6.2 urn:eyeling:ga: builtins (fast GA on *strings*)
-  // -----------------------------------------------------------------
-
-  // urn:eyeling:ga:solveString
-  // Schema: ( $target $mutProb $samples $seed $traceEvery $maxGenerations ) :solveString ( $gen $score $value $seed )
-  // Side effect: if traceEvery > 0, prints: <gen> TRACE (<score> "<value>")
-  if (pv === 'urn:eyeling:ga:solveString') {
-    if (!(g.s instanceof ListTerm) || g.s.elems.length != 6) return [];
-
-    const target = termToJsXsdStringNoLang(g.s.elems[0]);
-    const mutProbNum = parseNum(g.s.elems[1]);
-    const samplesNum = parseNum(g.s.elems[2]);
-    const seedNum = parseNum(g.s.elems[3]);
-    const traceEveryNum = parseNum(g.s.elems[4]);
-    const maxGenNum = parseNum(g.s.elems[5]);
-
-    if (target === null || mutProbNum === null || samplesNum === null || seedNum === null) return [];
-    if (traceEveryNum === null || maxGenNum === null) return [];
+  // string:mutateSelectBest
+  // Schema:
+  //   ( $samples $current $target $mutProb $seedState )
+  //     string:mutateSelectBest
+  //   ( $best $bestScore $seedState2 )
+  //
+  // Deterministic 31-bit LCG (same as the GA demo):
+  //   state = (1103515245 * state + 12345) % 2^31
+  // and randRound(N) = Math.round((state/2^31) * N) with state advanced once per draw.
+  if (pv === STRING_NS + 'mutateSelectBest') {
+    if (!(g.s instanceof ListTerm) || g.s.elems.length !== 5) return [];
+
+    const samplesNum = parseNum(g.s.elems[0]);
+    const current = termToJsXsdStringNoLang(g.s.elems[1]);
+    const target = termToJsXsdStringNoLang(g.s.elems[2]);
+    const mutProbNum = parseNum(g.s.elems[3]);
+    const seedNum = parseNum(g.s.elems[4]);
+
+    if (samplesNum === null || current === null || target === null || mutProbNum === null || seedNum === null)
+      return [];
+    if (current.length !== target.length) return [];
 
-    const mutProb = Math.max(0, Math.trunc(mutProbNum));
     const samples = Math.max(1, Math.trunc(samplesNum));
+    const mutProb = Math.max(0, Math.trunc(mutProbNum));
     const seed0 = Math.trunc(seedNum);
 
-    const traceEvery = Math.max(0, Math.trunc(traceEveryNum));
-    const maxGenerations = Math.max(0, Math.trunc(maxGenNum));
-
-    // Deterministic 31-bit LCG using BigInt arithmetic (matches the N3 version)
     let state = BigInt(seed0);
     const MOD = 2147483648n; // 2^31
     const A = 1103515245n;
@@ -3582,12 +3580,6 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
       return p === 0 ? ' ' : String.fromCharCode(64 + p);
     }
 
-    function randomText(len) {
-      let out = '';
-      for (let i = 0; i < len; i++) out += randomAlpha();
-      return out;
-    }
-
     function mutate(str) {
       let out = '';
       for (let i = 0; i < str.length; i++) {
@@ -3604,50 +3596,22 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
       return diffs;
     }
 
-    const pref = trace.getTracePrefixes() || PrefixEnv.newDefault();
-    function doTrace(gen, sc, val) {
-      const genLit = internLiteral(String(gen));
-      const scLit = internLiteral(String(sc));
-      const valLit = makeStringLiteral(val);
-      const obj = new ListTerm([scLit, valLit]);
-      const xStr = termToN3(genLit, pref);
-      const yStr = termToN3(obj, pref);
-      trace.writeTraceLine(`${xStr} TRACE ${yStr}`);
-    }
-
-    let generation = 0;
-    let current = randomText(target.length);
-    let currentScore = score(current);
-
-    if (traceEvery > 0 && generation % traceEvery === 0) doTrace(generation, currentScore, current);
-
-    while (currentScore !== 0) {
-      if (maxGenerations > 0 && generation >= maxGenerations) break;
-
-      let best = '';
-      let bestScore = Infinity;
-
-      for (let i = 0; i < samples; i++) {
-        const cand = mutate(current);
-        const candScore = score(cand);
-        if (candScore < bestScore) {
-          best = cand;
-          bestScore = candScore;
-        }
-      }
+    let best = '';
+    let bestScore = Infinity;
 
-      generation += 1;
-      current = best;
-      currentScore = bestScore;
-
-      if (traceEvery > 0 && generation % traceEvery === 0) doTrace(generation, currentScore, current);
+    for (let i = 0; i < samples; i++) {
+      const cand = mutate(current);
+      const candScore = score(cand);
+      if (candScore < bestScore) {
+        best = cand;
+        bestScore = candScore;
+      }
     }
 
     const outList = new ListTerm([
-      internLiteral(String(generation)),
-      internLiteral(String(currentScore)),
-      makeStringLiteral(current),
-      internLiteral(String(seed0)),
+      makeStringLiteral(best),
+      internLiteral(String(bestScore)),
+      internLiteral(state.toString()),
     ]);
 
     const s2 = unifyTerm(g.o, outList, subst);
@@ -3674,11 +3638,6 @@ function isBuiltinPred(p) {
     return true;
   }
 
-  // Eyeling extension: GA demo builtins
-  if (v === 'urn:eyeling:ga:solveString') {
-    return true;
-  }
-
   return (
     v.startsWith(CRYPTO_NS) ||
     v.startsWith(MATH_NS) ||

package/package.json

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