eyeprolog 1.3.3 → 1.3.7

package/README.md

@@ -86,6 +86,72 @@ error, and later quads still run. When a query has multiple indented answer
 descriptions, each description is checked and counted independently, so one
 failed expectation does not prevent the later ones from running.
 
+## Tabling and well-founded negation
+
+In normal mode, EyeProlog automatically tables eligible positive recursive
+predicates. For large finite, function-free Datalog dependency cones it may use
+one shared relation-wide table, so an open query such as `tc(X, Y)` computes a
+finite closure once and bound recursive calls can reuse indexed answers. The
+choice of when to use relation-wide tabling is an implementation optimization,
+not a language-level threshold or directive.
+
+Recursive nonterminals reached through `phrase/2-3` use a dedicated table
+scope keyed by the complete invocation rather than the caller's general memo.
+When a new input is seen, recursive DCGs that static analysis proves consume a
+list tail on every recursive step run directly without automatic tabling; this
+avoids building and retaining a family of suffix tables that cannot help the
+next distinct input. If the same `phrase/2-3` invocation repeats, normal tabling
+is enabled again and its small completed table can be reused. The retained
+phrase table is also bounded, with active fixed points never evicted. This
+keeps both long-running filters such as `\+ phrase((..., Pattern), Sequence)`
+and repeated same-input probes bounded without turning memory safety into a
+per-call cache-eviction cost.
+
+Recursion through negation is explicit. EyeProlog provides `tnot/1` for
+well-founded negation over finite, range-restricted, function-free Datalog
+components. Ordinary `\+/1` remains negation-as-failure and is not silently
+reinterpreted as WFS.
+
+```prolog
+move(1, 2).
+move(2, 1).
+win(X) :- move(X, Y), tnot(win(Y)).
+
+%% goal: win(X)
+```
+
+A cycle through `tnot/1` can leave atoms *undefined* rather than true or false.
+EyeProlog exposes those as conditional successes so they can participate in
+collectors such as `findall/3`; it does not currently expose a residual-program
+API. Direct `tnot/1` calls must be ground. Variables used in an eligible WFS
+rule are range-restricted by positive body literals before they are negated.
+
+The normal-mode statistics interface includes `wfs_fixpoint_rounds` and
+`wfs_undefined_answers`:
+
+```prolog
+statistics(wfs_fixpoint_rounds, Rounds).
+statistics(wfs_undefined_answers, UndefinedObservations).
+```
+
+Both automatic tabling and `tnot/1` are EyeProlog extensions. Strict ISO mode
+disables automatic tabling and does not provide `tnot/1`.
+
+## OpenRuleBench portable profile
+
+The `openrulebench/` directory contains a deterministic four-engine adaptation
+for EyeProlog, Trealla, Scryer, and SWI-Prolog. Its default `portable` profile
+keeps the characteristic joins, recursive closures, and WFS cases while
+avoiding benchmark sizes that require multi-gigabyte collectors on some
+engines. Run EyeProlog's complete profile with:
+
+```sh
+./openrulebench/run-eyeprolog.sh
+```
+
+The benchmark README records the expected answer counts. Timing values are
+machine-dependent; use the same generated profile when comparing engines.
+
 ## Strict ISO/IEC 13211-1 core
 
 For portability and conformance work, run the Part 1 core with Technical
@@ -143,12 +209,20 @@ Trealla/Scryer organization for predicates such as `member/2`, `memberchk/2`,
 `length(Xs, N)` enumerates lists of increasing length together with `N = 0, 1,
 2, ...`.
 
+`library(iso_ext)` is also accepted as a common interop module name.
+EyeProlog exports `call_nth/2` there, so Scryer-style source can explicitly use
+`:- use_module(library(iso_ext)).`; unqualified source may still autoload it.
+The aligned `library(lists)` and `library(iso_ext)` exports are kept disjoint so
+they can be imported together without an accidental import conflict. EyeProlog's
+legacy `library(prologue)` remains a compatibility umbrella and should be
+selectively imported when mixed with the aligned modules.
+
 Outside `--iso-strict`, an otherwise undefined unqualified call may autoload a
 predicate only when the interop profile has one canonical EyeProlog provider.
-For example, `member/2` autoloads from `library(lists)`, while `between/3` and
-`call_nth/2` can use EyeProlog's internal Prologue implementation without
-requiring portable source to name `library(prologue)`. Use `--no-autoload` to
-disable this convenience. Strict ISO mode never autoloads library predicates.
+For example, `member/2` autoloads from `library(lists)`, `call_nth/2` from
+`library(iso_ext)`, and `between/3` from EyeProlog's internal
+`library(prologue)` implementation. Use `--no-autoload` to disable this
+convenience. Strict ISO mode never autoloads library predicates.
 
 Use `-w` / `--warnings` to diagnose dependencies outside the interop profile,
 or `--portable` to make such diagnostics fail the run. This catches both

package/examples/book/README.md

@@ -56,7 +56,8 @@ npm run generate
 ## Chapter 7: Failure, negation, and quantification
 
 - [01-allowed.pl](chapter-07/01-allowed.pl)
-- [02-all_tests_pass.pl](chapter-07/02-all_tests_pass.pl)
+- [02-move.pl](chapter-07/02-move.pl)
+- [03-all_tests_pass.pl](chapter-07/03-all_tests_pass.pl)
 
 ## Chapter 8: Collecting and choosing answers
 

package/examples/book/chapter-07/02-move.pl

@@ -0,0 +1,4 @@
+% From The Art of EyeProlog, Chapter 7.
+move(a, b).
+move(b, a).
+win(X) :- move(X, Y), tnot(win(Y)).

package/examples/book/chapter-08/01-findall.pl

@@ -1,6 +1,7 @@
 % From The Art of EyeProlog, Chapter 8.
 :- use_module(library(aggregate)).
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 findall(Template, Goal, List).
 countall(Goal, Count).

package/examples/book/chapter-39/04-cost.pl

@@ -1,6 +1,7 @@
 % From The Art of EyeProlog, Chapter 39.
 :- use_module(library(aggregate)).
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 cost(a, 8).
 cost(b, 3).

package/examples/chart-parser.pl

@@ -1,4 +1,5 @@
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 % A tiny automatically tabled chart parser for a context-free grammar.
 %

package/examples/dog.pl

@@ -1,4 +1,5 @@
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 % Dog-license compliance rule adapted from Eyeling dog.n3.
 %

package/examples/donald-gerald-robert.pl

@@ -1,4 +1,5 @@
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 % A pandigital cryptarithm: DONALD + GERALD = ROBERT.
 %

package/examples/equality-saturation.pl

@@ -1,6 +1,7 @@
 :- use_module(library(aggregate)).
 :- use_module(library(prologue), [between/3]).
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 % Bounded equality saturation over tiny arithmetic expression terms.
 %

package/examples/job-shop-scheduling.pl

@@ -1,6 +1,7 @@
 :- use_module(library(aggregate)).
 :- use_module(library(prologue), [between/3]).
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 % Tiny job-shop scheduling benchmark.
 %

package/examples/knapsack-optimization.pl

@@ -1,5 +1,6 @@
 :- use_module(library(aggregate)).
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 % 0/1 knapsack optimization with aggregate_max/5.
 %

package/examples/knuth-bendix-completion.pl

@@ -1,4 +1,5 @@
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 % Bounded Knuth-Bendix-style completion for append/2 terms.
 %

package/examples/matrix-chain-order.pl

@@ -1,6 +1,7 @@
 :- use_module(library(aggregate)).
 :- use_module(library(prologue), [between/3]).
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 % Matrix-chain multiplication order by automatically tabled interval dynamic programming.
 %

package/examples/missionaries-cannibals.pl

@@ -1,5 +1,6 @@
 :- use_module(library(prologue), [between/3]).
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 % Missionaries-and-cannibals river crossing as guarded state-space search.
 %

package/examples/prime-range.pl

@@ -1,5 +1,6 @@
 :- use_module(library(prologue), [between/3]).
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 % Prime ranges and Euler totient over finite integer domains.
 %

package/examples/register-allocation.pl

@@ -1,5 +1,6 @@
 :- use_module(library(aggregate)).
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 % Register allocation as bounded graph coloring with spilling.
 %

package/examples/send-more-money.pl

@@ -1,4 +1,5 @@
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 % Cryptarithm search for SEND + MORE = MONEY.
 %

package/examples/stable-marriage.pl

@@ -1,4 +1,5 @@
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 % Stable-marriage search with explicit blocking-pair detection.
 %

package/examples/totient-summatory.pl

@@ -1,6 +1,7 @@
 :- use_module(library(aggregate)).
 :- use_module(library(prologue), [between/3]).
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 % Euler totients and coprimality by automatically tabled Euclidean gcd.
 %

package/examples/weighted-interval-scheduling.pl

@@ -1,5 +1,6 @@
 :- use_module(library(aggregate)).
 :- use_module(library(lists)).
+:- use_module(library(iso_ext)).
 
 % Weighted interval scheduling via automatically tabled dynamic programming.
 %

package/index.d.ts

@@ -1,4 +1,8 @@
 export interface EyePrologStats {
+  /** Alternating-fixed-point rounds used to build WFS models. */
+  wfs_fixpoint_rounds: number;
+  /** Undefined WFS answers observed while producing query results. */
+  wfs_undefined_answers: number;
   [key: string]: number;
 }
 
@@ -97,6 +101,9 @@ export interface EyePrologPredicateGroup {
   recursive: boolean;
   listTailRecursive: boolean;
   tableInputPositions: number[];
+  tableAllVariants: boolean;
+  /** True when the group is evaluated by EyeProlog's finite-Datalog WFS evaluator. */
+  wfsDatalog: boolean;
   negationStratum: number | null;
 }
 

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.3.3",
+  "version": "1.3.7",
   "description": "EyeProlog turns facts and rules into answers and proofs.",
   "type": "module",
   "main": "./index.js",

package/src/datalog.js

@@ -0,0 +1,354 @@
+// Indexed semi-naive evaluator for finite, range-restricted positive Datalog.
+//
+// Program analysis marks only large function-free recursive dependency cones
+// for this path.  Rows are derived once and propagated through an agenda; each
+// newly-added row fires only the rule occurrences that mention its predicate.
+// This avoids replaying the whole recursive program on every table round.
+
+import { ATOM, COMPOUND, VAR } from './term.js';
+import { numberValueKey } from './number-value.js';
+
+const EMPTY_ARRAY = Object.freeze([]);
+
+function predicateKey(module, name, arity) {
+  return `${module ?? 'user'}:${name}/${arity}`;
+}
+
+const scalarKeyCache = new WeakMap();
+
+function scalarKey(term) {
+  const cached = scalarKeyCache.get(term);
+  if (cached != null) return cached;
+  const key = term.type === 'number'
+    ? `number\u0000${numberValueKey(term.name)}`
+    : `${term.type}\u0000${term.name}`;
+  scalarKeyCache.set(term, key);
+  return key;
+}
+
+function sameScalar(left, right) {
+  return scalarKey(left) === scalarKey(right);
+}
+
+function tupleKey(tuple) {
+  if (tuple.length === 1) return scalarKey(tuple[0]);
+  return tuple.map(scalarKey).join('\u0001');
+}
+
+export class DatalogRelation {
+  constructor(arity) {
+    this.arity = arity;
+    this.rows = [];
+    this.keys = arity > 2 ? new Set() : null;
+    this.unaryKeys = arity === 1 ? new Set() : null;
+    this.binaryKeys = arity === 2 ? new Map() : null;
+    this.indexes = Array.from({ length: arity }, () => new Map());
+  }
+
+  containsKeys(parts) {
+    if (this.arity === 0) return this.rows.length !== 0;
+    if (this.arity === 1) return this.unaryKeys.has(parts[0]);
+    if (this.arity === 2) return this.binaryKeys.get(parts[0])?.has(parts[1]) === true;
+    return this.keys.has(parts.join('\u0001'));
+  }
+
+  rememberKeys(parts) {
+    if (this.arity === 0) return;
+    if (this.arity === 1) {
+      this.unaryKeys.add(parts[0]);
+      return;
+    }
+    if (this.arity === 2) {
+      let seconds = this.binaryKeys.get(parts[0]);
+      if (seconds == null) this.binaryKeys.set(parts[0], seconds = new Set());
+      seconds.add(parts[1]);
+      return;
+    }
+    this.keys.add(parts.join('\u0001'));
+  }
+
+  add(tuple) {
+    const parts = tuple.map(scalarKey);
+    if (this.containsKeys(parts)) return false;
+    this.rememberKeys(parts);
+    this.appendRow(tuple, parts);
+    return true;
+  }
+
+  addProjected(args, bindings) {
+    const tuple = new Array(args.length);
+    const parts = new Array(args.length);
+    for (let i = 0; i < args.length; i++) {
+      const value = args[i].type === VAR ? bindings.get(args[i].name) : args[i];
+      if (value == null || value.type === VAR) return null;
+      tuple[i] = value;
+      parts[i] = scalarKey(value);
+    }
+    if (this.containsKeys(parts)) return null;
+    this.rememberKeys(parts);
+    this.appendRow(tuple, parts);
+    return tuple;
+  }
+
+  appendRow(tuple, parts) {
+    const rowIndex = this.rows.length;
+    this.rows.push(tuple);
+    for (let i = 0; i < tuple.length; i++) {
+      let bucket = this.indexes[i].get(parts[i]);
+      if (bucket == null) this.indexes[i].set(parts[i], bucket = []);
+      bucket.push(rowIndex);
+    }
+  }
+
+  has(tuple) {
+    return this.containsKeys(tuple.map(scalarKey));
+  }
+
+  candidateIndexes(args, bindings) {
+    let selected = null;
+    for (let i = 0; i < args.length; i++) {
+      const value = resolvePatternTerm(args[i], bindings);
+      if (value == null) continue;
+      const bucket = this.indexes[i].get(scalarKey(value)) ?? EMPTY_ARRAY;
+      if (selected == null || bucket.length < selected.length) selected = bucket;
+      if (selected.length === 0) break;
+    }
+    return selected;
+  }
+}
+
+function directLiteral(goal, module) {
+  if (goal?.type !== COMPOUND && goal?.type !== ATOM) return null;
+  return {
+    key: predicateKey(goal.module ?? module, goal.name, goal.arity),
+    name: goal.name,
+    arity: goal.arity,
+    module: goal.module ?? module,
+    args: goal.args ?? EMPTY_ARRAY,
+  };
+}
+
+function dependencyCone(program, rootGroup) {
+  const groups = [];
+  const seen = new Set();
+  const stack = [rootGroup];
+  while (stack.length > 0) {
+    const group = stack.pop();
+    const key = predicateKey(group.module, group.name, group.arity);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    groups.push(group);
+    for (const clause of group.clauses) {
+      for (const goal of clause.body) {
+        const literal = directLiteral(goal, group.module);
+        if (!literal) continue;
+        const target = program.findGroup(literal.name, literal.arity, literal.module);
+        if (target) stack.push(target);
+      }
+    }
+  }
+  return groups;
+}
+
+function compileProgram(program, rootGroup) {
+  const groups = dependencyCone(program, rootGroup);
+  const relations = new Map();
+  const groupByKey = new Map();
+  const rules = [];
+  const triggers = new Map();
+
+  for (const group of groups) {
+    const key = predicateKey(group.module, group.name, group.arity);
+    relations.set(key, new DatalogRelation(group.arity));
+    groupByKey.set(key, group);
+  }
+
+  for (const group of groups) {
+    const headKey = predicateKey(group.module, group.name, group.arity);
+    for (const clause of group.clauses) {
+      const headArgs = clause.head.args ?? EMPTY_ARRAY;
+      if (clause.body.length === 0) continue;
+      const body = clause.body.map((goal) => directLiteral(goal, group.module));
+      if (body.some((literal) => literal == null)) continue;
+      const rule = { headKey, headArgs, body };
+      rules.push(rule);
+      for (let index = 0; index < body.length; index++) {
+        const key = body[index].key;
+        let entries = triggers.get(key);
+        if (entries == null) triggers.set(key, entries = []);
+        entries.push({ rule, literalIndex: index });
+      }
+    }
+  }
+
+  return { groups, groupByKey, relations, rules, triggers };
+}
+
+function resolvePatternTerm(term, bindings) {
+  if (term.type === VAR) return bindings.get(term.name) ?? null;
+  return term;
+}
+
+function matchTupleMutable(args, tuple, bindings) {
+  const added = [];
+  for (let i = 0; i < args.length; i++) {
+    const pattern = args[i];
+    if (pattern.type === VAR) {
+      const current = bindings.get(pattern.name);
+      if (current != null) {
+        if (!sameScalar(current, tuple[i])) {
+          for (let j = added.length - 1; j >= 0; j--) bindings.delete(added[j]);
+          return null;
+        }
+      } else {
+        bindings.set(pattern.name, tuple[i]);
+        added.push(pattern.name);
+      }
+      continue;
+    }
+    if (!sameScalar(pattern, tuple[i])) {
+      for (let j = added.length - 1; j >= 0; j--) bindings.delete(added[j]);
+      return null;
+    }
+  }
+  return added;
+}
+
+function undoBindings(bindings, added) {
+  for (let i = added.length - 1; i >= 0; i--) bindings.delete(added[i]);
+}
+
+function estimateLiteral(literal, relation, bindings) {
+  const candidates = relation.candidateIndexes(literal.args, bindings);
+  return candidates == null ? relation.rows.length : candidates.length;
+}
+
+function forEachBinding(body, relations, callback, bindings, remaining) {
+  if (remaining.length === 0) {
+    callback(bindings);
+    return;
+  }
+
+  let bestPosition = 0;
+  let bestEstimate = Infinity;
+  for (let position = 0; position < remaining.length; position++) {
+    const literal = body[remaining[position]];
+    const relation = relations.get(literal.key);
+    const estimate = relation == null ? 0 : estimateLiteral(literal, relation, bindings);
+    if (estimate < bestEstimate) {
+      bestEstimate = estimate;
+      bestPosition = position;
+      if (estimate === 0) return;
+    }
+  }
+
+  const literalIndex = remaining[bestPosition];
+  const literal = body[literalIndex];
+  const relation = relations.get(literal.key);
+  if (!relation) return;
+  const candidates = relation.candidateIndexes(literal.args, bindings);
+  const nextRemaining = remaining.length === 1
+    ? EMPTY_ARRAY
+    : [...remaining.slice(0, bestPosition), ...remaining.slice(bestPosition + 1)];
+
+  if (candidates == null) {
+    for (let rowIndex = 0; rowIndex < relation.rows.length; rowIndex++) {
+      const added = matchTupleMutable(literal.args, relation.rows[rowIndex], bindings);
+      if (added) {
+        forEachBinding(body, relations, callback, bindings, nextRemaining);
+        undoBindings(bindings, added);
+      }
+    }
+    return;
+  }
+
+  for (const rowIndex of candidates) {
+    const added = matchTupleMutable(literal.args, relation.rows[rowIndex], bindings);
+    if (added) {
+      forEachBinding(body, relations, callback, bindings, nextRemaining);
+      undoBindings(bindings, added);
+    }
+  }
+}
+
+function instantiateTuple(args, bindings) {
+  const tuple = new Array(args.length);
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const value = arg.type === VAR ? bindings.get(arg.name) : arg;
+    if (value == null || value.type === VAR) return null;
+    tuple[i] = value;
+  }
+  return tuple;
+}
+
+export function evaluatePositiveDatalog(program, rootGroup) {
+  const compiled = compileProgram(program, rootGroup);
+  const agenda = [];
+  let ruleFirings = 0;
+  let derivedFacts = 0;
+
+  const add = (key, tuple) => {
+    const relation = compiled.relations.get(key);
+    if (!relation || !relation.add(tuple)) return false;
+    agenda.push({ key, tuple });
+    derivedFacts++;
+    return true;
+  };
+
+  // Seed all EDB/source facts in the dependency cone. Source order is retained
+  // within each predicate relation, which keeps answer enumeration stable.
+  for (const group of compiled.groups) {
+    const key = predicateKey(group.module, group.name, group.arity);
+    for (const clause of group.clauses) {
+      if (clause.body.length !== 0) continue;
+      const tuple = clause.head.args ?? EMPTY_ARRAY;
+      if (tuple.every((term) => term.type !== VAR)) add(key, tuple);
+    }
+  }
+
+  for (let cursor = 0; cursor < agenda.length; cursor++) {
+    const event = agenda[cursor];
+    const triggerEntries = compiled.triggers.get(event.key) ?? EMPTY_ARRAY;
+    for (const { rule, literalIndex } of triggerEntries) {
+      const fixed = rule.body[literalIndex];
+      const bindings = new Map();
+      if (!matchTupleMutable(fixed.args, event.tuple, bindings)) continue;
+      const remaining = [];
+      for (let i = 0; i < rule.body.length; i++) if (i !== literalIndex) remaining.push(i);
+      ruleFirings++;
+      forEachBinding(rule.body, compiled.relations, (completeBindings) => {
+        const relation = compiled.relations.get(rule.headKey);
+        const tuple = relation?.addProjected(rule.headArgs, completeBindings) ?? null;
+        if (tuple != null) {
+          agenda.push({ key: rule.headKey, tuple });
+          derivedFacts++;
+        }
+      }, bindings, remaining);
+    }
+  }
+
+  return {
+    relations: compiled.relations,
+    groups: compiled.groups,
+    ruleFirings,
+    derivedFacts,
+  };
+}
+
+export function relationForDatalogGroup(model, group) {
+  return model.relations.get(predicateKey(group.module, group.name, group.arity)) ?? null;
+}
+
+export function datalogCandidateIndexes(relation, goalArgs, env, derefValue, scalarKeyForTerm) {
+  let selected = null;
+  for (let i = 0; i < goalArgs.length; i++) {
+    const value = derefValue(goalArgs[i], env);
+    if (value?.type !== 'atom' && value?.type !== 'string' && value?.type !== 'number') continue;
+    const key = scalarKeyForTerm ? scalarKeyForTerm(value) : scalarKey(value);
+    const bucket = relation.indexes[i].get(key) ?? EMPTY_ARRAY;
+    if (selected == null || bucket.length < selected.length) selected = bucket;
+    if (selected.length === 0) break;
+  }
+  return selected;
+}