eyeling 1.32.0 → 1.33.0

package/lib/eyelang/solver.mjs

@@ -0,0 +1,237 @@
+// Depth-first eyelang solver with builtin dispatch, memoization, and guarded recursion handling.
+// Most semantic decisions still flow through unification; optimizations only select candidates earlier.
+import { COMPOUND, Env, flattenConjunction, freshTerm, termToString, unify, variantTerms } from './term.mjs';
+import { createDefaultRegistry } from './builtins/registry.mjs';
+import { selectClauseCandidates } from './program.mjs';
+
+let freshCounter = 0;
+
+export function nextFreshId() {
+  return ++freshCounter;
+}
+
+export class Solver {
+  constructor(program, options = {}) {
+    this.program = program;
+    this.registry = options.registry ?? createDefaultRegistry();
+    this.maxDepth = options.maxDepth ?? 100000;
+    this.solutionLimit = options.solutionLimit ?? 10000000;
+    this.solutionsSeen = 0;
+    this.active = [];
+    this.memo = new Map();
+    this.stats = {
+      completed_goal_lists: 0,
+      solve_goals_calls: 0,
+      solve_one_goal_calls: 0,
+      unify_calls: 0,
+      max_depth: 0,
+      max_goal_count: 0,
+      deterministic_builtin_successes: 0,
+      deterministic_builtin_failures: 0,
+    };
+  }
+
+  cloneForInnerGoal(solutionLimit = this.solutionLimit) {
+    const solver = new Solver(this.program, { registry: this.registry, maxDepth: this.maxDepth, solutionLimit });
+    solver.memo = this.memo;
+    return solver;
+  }
+
+  *solve(goals, env = new Env(), depth = 0) {
+    this.stats.solve_goals_calls++;
+    this.stats.max_depth = Math.max(this.stats.max_depth, depth);
+    this.stats.max_goal_count = Math.max(this.stats.max_goal_count, goals.length);
+    if (depth > this.maxDepth || this.solutionsSeen >= this.solutionLimit) return;
+    if (!Array.isArray(goals)) goals = [goals];
+
+    if (goals.length === 0) {
+      this.solutionsSeen++;
+      this.stats.completed_goal_lists++;
+      yield env;
+      return;
+    }
+
+    // eyelang normally solves left-to-right, but ready deterministic builtins can
+    // be run early as pure filters. This gives large pruning wins without
+    // reordering user predicates or nondeterministic generators.
+    const selectedIndex = selectReadyDeterministicBuiltin(goals, env, this.registry);
+    const goal = goals[selectedIndex];
+    const rest = selectedIndex === 0 ? goals.slice(1) : [...goals.slice(0, selectedIndex), ...goals.slice(selectedIndex + 1)];
+    if (goal.type === COMPOUND && goal.name === ',' && goal.arity === 2) {
+      yield* this.solve([...flattenConjunction(goal), ...rest], env, depth + 1);
+      return;
+    }
+
+    const def = goal.type === COMPOUND ? this.registry.get(goal.name, goal.arity) : null;
+    if (def && builtinIsReadyOrAuthoritative(def, this, goal, env)) {
+      let produced = false;
+      for (const next of def.handler({ solver: this, goal, env })) {
+        produced = true;
+        yield* this.solve(rest, next, depth + 1);
+        if (this.solutionsSeen >= this.solutionLimit) return;
+      }
+      if (def.deterministic) {
+        if (produced) this.stats.deterministic_builtin_successes++;
+        else this.stats.deterministic_builtin_failures++;
+      }
+      return;
+    }
+
+    yield* this.solveUserGoal(goal, rest, env, depth);
+  }
+
+  activeVariant(goal, env) {
+    return this.active.some((entry) => variantTerms(goal, env, entry.goal, entry.env));
+  }
+
+  *solveUserGoal(goal, rest, env, depth) {
+    this.stats.solve_one_goal_calls++;
+    if (depth > this.maxDepth || this.solutionsSeen >= this.solutionLimit) return;
+    if (goal.type !== COMPOUND) return;
+    const group = this.program.findGroup(goal.name, goal.arity);
+    if (!group) return;
+    if (group.memoized) {
+      yield* this.solveMemoizedGoal(group, goal, rest, env, depth);
+      return;
+    }
+    yield* this.solveUserGoalUncached(group, goal, rest, env, depth);
+  }
+
+  *solveMemoizedGoal(group, goal, rest, env, depth) {
+    // Memoization only pays off when at least one argument is bound. A fully
+    // open call would require storing the entire relation and can mask useful
+    // goal-ordering behavior, so it falls back to the normal path.
+    const key = memoKey(goal, env);
+    if (!key.hasBound) {
+      yield* this.solveUserGoalUncached(group, goal, rest, env, depth);
+      return;
+    }
+    const mapKey = `${goal.name}/${goal.arity}:${key.text}`;
+    let entry = this.memo.get(mapKey);
+    if (!entry) {
+      entry = { computing: false, complete: false, answers: [] };
+      this.memo.set(mapKey, entry);
+    }
+    if (!entry.complete && !entry.computing) {
+      entry.computing = true;
+      const collector = this.cloneForInnerGoal();
+      for (const answerEnv of collector.solveUserGoalUncached(group, goal, [], env.clone(), depth)) {
+        entry.answers.push(goal.args.map((arg) => importResolved(arg, answerEnv)));
+      }
+      entry.computing = false;
+      entry.complete = true;
+    }
+    if (!entry.complete && entry.computing) {
+      yield* this.solveUserGoalUncached(group, goal, rest, env, depth);
+      return;
+    }
+    for (const answerArgs of entry.answers) {
+      const next = env.clone();
+      let ok = true;
+      for (let i = 0; i < goal.arity; i++) {
+        this.stats.unify_calls++;
+        if (!unify(goal.args[i], answerArgs[i], next)) { ok = false; break; }
+      }
+      if (ok) yield* this.solve(rest, next, depth + 1);
+      if (this.solutionsSeen >= this.solutionLimit) return;
+    }
+  }
+
+  *solveUserGoalUncached(group, goal, rest, env, depth) {
+    if (this.activeVariant(goal, env)) return;
+    // Program indexes provide candidate clauses, but every candidate is still
+    // freshened and unified below. The index is a performance hint, not a
+    // semantic shortcut.
+    const candidates = selectClauseCandidates(group, goal, env);
+    for (const pass of [candidates.primary, candidates.fallback]) {
+      for (const clause of pass) {
+        if (headCannotMatch(goal, clause.head, env)) continue;
+        const id = nextFreshId();
+        const freshHead = freshTerm(clause.head, id);
+        const freshBody = clause.body.map((term) => freshTerm(term, id));
+        const next = env.clone();
+        this.stats.unify_calls++;
+        if (!unify(goal, freshHead, next)) continue;
+        if (freshBody.length === 0) {
+          yield* this.solve(rest, next, depth + 1);
+        } else {
+          yield* this.solveRuleBodyThenRest(goal, env, freshBody, rest, next, depth);
+        }
+        if (this.solutionsSeen >= this.solutionLimit) return;
+      }
+    }
+  }
+  *solveRuleBodyThenRest(goal, goalEnv, body, rest, env, depth) {
+    // Match the C engine's active-call lifetime: the active guard protects
+    // expansion of the current rule body, but it must be released before
+    // the caller's remaining goals are solved. Keeping the goal active
+    // through rest goals over-prunes valid transitive/recursive derivations.
+    this.active.push({ goal, env: goalEnv });
+    for (const bodyEnv of this.solve(body, env, depth + 1)) {
+      if (this.solutionsSeen > 0) this.solutionsSeen--;
+      this.active.pop();
+      yield* this.solve(rest, bodyEnv, depth + 1);
+      this.active.push({ goal, env: goalEnv });
+      if (this.solutionsSeen >= this.solutionLimit) break;
+    }
+    this.active.pop();
+  }
+
+}
+
+
+function builtinIsReadyOrAuthoritative(def, solver, goal, env) {
+  if (typeof def.shouldUse === 'function' && !def.shouldUse({ solver, goal, env })) return false;
+  if (typeof def.ready !== 'function') return true;
+  if (def.ready(goal, env)) return true;
+  return !def.fallbackWhenNotReady;
+}
+
+function selectReadyDeterministicBuiltin(goals, env, registry) {
+  for (let i = 0; i < goals.length; i++) {
+    const goal = goals[i];
+    if (goal.type !== COMPOUND) continue;
+    const def = registry.get(goal.name, goal.arity);
+    if (!def?.deterministic || typeof def.ready !== 'function') continue;
+    if (typeof def.shouldUse === 'function') continue;
+    if (def.ready(goal, env)) return i;
+  }
+  return 0;
+}
+
+function headCannotMatch(goal, head, env) {
+  if (goal.type !== COMPOUND || head.type !== COMPOUND) return false;
+  if (goal.name !== head.name || goal.arity !== head.arity) return true;
+  for (let i = 0; i < goal.arity; i++) {
+    const a = goal.args[i];
+    const b = head.args[i];
+    // Keep this only as a cheap scalar rejection. unify() remains authoritative.
+    const da = derefForLocal(a, env);
+    if (da.args?.length === 0 && ['atom', 'string', 'number'].includes(da.type) && ['atom', 'string', 'number'].includes(b.type) && da.name !== b.name) return true;
+  }
+  return false;
+}
+
+function derefForLocal(term, env) {
+  let current = term;
+  while (current.type === 'var' && env.has(current.name)) current = env.get(current.name);
+  return current;
+}
+
+function memoKey(goal, env) {
+  let hasBound = false;
+  const parts = goal.args.map((arg) => {
+    const value = derefForLocal(arg, env);
+    if (value.type !== 'var') hasBound = true;
+    return value.type === 'var' ? '_' : termToString(value, env, true);
+  });
+  return { hasBound, text: parts.join('|') };
+}
+
+function importResolved(term, env) {
+  const { copyResolved } = termModuleCache;
+  return copyResolved(term, env);
+}
+
+// Avoid circular import surprises in older Node loaders.
+import * as termModuleCache from './term.mjs';

package/lib/eyelang/term.mjs

@@ -0,0 +1,328 @@
+// Term model, environments, unification, readback, and ordering helpers.
+// This file is intentionally dependency-free because nearly every other module imports it.
+export const VAR = 'var';
+export const ATOM = 'atom';
+export const STRING = 'string';
+export const NUMBER = 'number';
+export const COMPOUND = 'compound';
+
+export class Term {
+  constructor(type, name, args = []) {
+    this.type = type;
+    this.name = String(name ?? '');
+    this.args = args;
+  }
+  get arity() {
+    return this.args.length;
+  }
+}
+
+export const variable = (name) => new Term(VAR, name);
+export const atom = (name) => new Term(ATOM, name);
+export const stringTerm = (value) => new Term(STRING, value);
+export const numberTerm = (value) => new Term(NUMBER, value);
+export const compound = (name, args = []) => new Term(COMPOUND, name, args);
+export const emptyList = () => atom('[]');
+export const cons = (head, tail) => compound('.', [head, tail]);
+
+export class Env {
+  constructor(bindings) {
+    this.bindings = bindings ? new Map(bindings) : new Map();
+  }
+  clone() {
+    return new Env(this.bindings);
+  }
+  has(name) {
+    return this.bindings.has(name);
+  }
+  get(name) {
+    return this.bindings.get(name);
+  }
+  bind(name, term) {
+    this.bindings.set(name, term);
+  }
+}
+
+export function deref(term, env) {
+  // Follow variable bindings until a non-variable term is reached. The seen set
+  // protects readback from accidental cycles in partially constructed terms.
+  let current = term;
+  const seen = new Set();
+  while (current?.type === VAR && env?.has(current.name)) {
+    if (seen.has(current.name)) break;
+    seen.add(current.name);
+    current = env.get(current.name);
+  }
+  return current;
+}
+
+export function isScalar(term) {
+  return term && (term.type === ATOM || term.type === STRING || term.type === NUMBER);
+}
+
+export function isEmptyList(term) {
+  return term?.type === ATOM && term.name === '[]';
+}
+
+export function isCons(term) {
+  return term?.type === COMPOUND && term.name === '.' && term.arity === 2;
+}
+
+export function isConjunction(term) {
+  return term?.type === COMPOUND && term.name === ',' && term.arity === 2;
+}
+
+export function unify(left, right, env) {
+  // Iterative unification avoids deep JavaScript recursion on long lists or
+  // deeply nested compounds. Bindings are written into the supplied Env.
+  const stack = [[left, right]];
+  while (stack.length) {
+    let [a, b] = stack.pop();
+    a = deref(a, env);
+    b = deref(b, env);
+
+    if (a.type === VAR && b.type === VAR && a.name === b.name) continue;
+    if (a.type === VAR) {
+      env.bind(a.name, b);
+      continue;
+    }
+    if (b.type === VAR) {
+      env.bind(b.name, a);
+      continue;
+    }
+
+    if (a.type !== b.type) {
+      if (isScalar(a) && isScalar(b) && a.name === b.name) continue;
+      return false;
+    }
+
+    if (isScalar(a)) {
+      if (a.name !== b.name) return false;
+      continue;
+    }
+
+    if (a.type === COMPOUND) {
+      if (a.name !== b.name || a.arity !== b.arity) return false;
+      for (let i = a.arity - 1; i >= 0; i--) stack.push([a.args[i], b.args[i]]);
+      continue;
+    }
+
+    return false;
+  }
+  return true;
+}
+
+export function cloneTerm(term) {
+  return new Term(term.type, term.name, term.args.map(cloneTerm));
+}
+
+export function freshTerm(term, suffix) {
+  if (term.type === VAR) return variable(`${term.name}#${suffix}`);
+  return new Term(term.type, term.name, term.args.map((arg) => freshTerm(arg, suffix)));
+}
+
+export function copyResolved(term, env) {
+  const resolved = deref(term, env);
+  if (resolved.type === VAR) return variable(resolved.name);
+  return new Term(resolved.type, resolved.name, resolved.args.map((arg) => copyResolved(arg, env)));
+}
+
+export function termIsGround(term, env = new Env()) {
+  const resolved = deref(term, env);
+  if (resolved.type === VAR) return false;
+  return resolved.args.every((arg) => termIsGround(arg, env));
+}
+
+const graphicAtomChars = new Set('#$&*+-/<=>?@^~\\'.split(''));
+
+function atomNeedsQuotes(name) {
+  if (!name) return true;
+  if (name === '[]') return false;
+  if (/^[a-z][A-Za-z0-9_]*$/.test(name)) return false;
+  for (const ch of name) if (!graphicAtomChars.has(ch)) return true;
+  return false;
+}
+
+function quoteAtom(name) {
+  let out = "'";
+  for (const ch of name) {
+    if (ch === "'") out += "''";
+    else if (ch === '\\') out += '\\\\';
+    else if (ch === '\n') out += '\\n';
+    else if (ch === '\t') out += '\\t';
+    else out += ch;
+  }
+  return out + "'";
+}
+
+function writeAtom(name) {
+  return atomNeedsQuotes(name) ? quoteAtom(name) : name;
+}
+
+function writeString(value, quoteStrings) {
+  if (!quoteStrings) return value;
+  let out = '"';
+  for (const ch of value) {
+    if (ch === '"' || ch === '\\') out += `\\${ch}`;
+    else if (ch === '\n') out += '\\n';
+    else out += ch;
+  }
+  return out + '"';
+}
+
+function writeList(term, env) {
+  const parts = [];
+  let cursor = term;
+  while (true) {
+    cursor = deref(cursor, env);
+    if (isEmptyList(cursor)) return `[${parts.join(', ')}]`;
+    if (!isCons(cursor)) {
+      if (parts.length) return `[${parts.join(', ')} | ${termToString(cursor, env, true)}]`;
+      return `[${termToString(cursor, env, true)}]`;
+    }
+    parts.push(termToString(cursor.args[0], env, true));
+    cursor = cursor.args[1];
+  }
+}
+
+export function termToString(term, env = new Env(), quoteStrings = true) {
+  const resolved = deref(term, env);
+  if (resolved.type === VAR) return resolved.name;
+  if (isCons(resolved)) return writeList(resolved, env);
+  if (resolved.type === STRING) return writeString(resolved.name, quoteStrings);
+  if (resolved.type === ATOM) return writeAtom(resolved.name);
+  if (resolved.type === NUMBER) return resolved.name;
+  if (isConjunction(resolved)) {
+    const parts = [];
+    let cursor = resolved;
+    while (true) {
+      cursor = deref(cursor, env);
+      if (isConjunction(cursor)) {
+        parts.push(termToString(cursor.args[0], env, true));
+        cursor = cursor.args[1];
+      } else {
+        parts.push(termToString(cursor, env, true));
+        break;
+      }
+    }
+    return `(${parts.join(', ')})`;
+  }
+  return `${writeAtom(resolved.name)}(${resolved.args.map((arg) => termToString(arg, env, true)).join(', ')})`;
+}
+
+export function lexicalValue(term, env) {
+  const resolved = deref(term, env);
+  if (resolved.type === VAR) return null;
+  if (resolved.type === ATOM || resolved.type === STRING || resolved.type === NUMBER) return resolved.name;
+  return termToString(resolved, env, true);
+}
+
+export function properListItems(list, env) {
+  const items = [];
+  let cursor = deref(list, env);
+  while (isCons(cursor)) {
+    items.push(cursor.args[0]);
+    cursor = deref(cursor.args[1], env);
+  }
+  if (!isEmptyList(cursor)) return null;
+  return items;
+}
+
+export function listFromItems(items, start = 0, end = items.length, tail = emptyList()) {
+  let result = tail;
+  for (let i = end - 1; i >= start; i--) result = cons(items[i], result);
+  return result;
+}
+
+export function flattenConjunction(goal) {
+  const out = [];
+  const stack = [goal];
+  while (stack.length) {
+    const current = stack.pop();
+    if (isConjunction(current)) {
+      stack.push(current.args[1], current.args[0]);
+    } else {
+      out.push(current);
+    }
+  }
+  return out;
+}
+
+export function termSignature(term) {
+  return term?.type === COMPOUND ? `${term.name}/${term.arity}` : null;
+}
+
+export function variantTerms(left, leftEnv, right, rightEnv, pairs = new Map(), reverse = new Map()) {
+  left = deref(left, leftEnv);
+  right = deref(right, rightEnv);
+  if (left.type === VAR || right.type === VAR) {
+    if (left.type !== VAR || right.type !== VAR) return false;
+    if (pairs.has(left.name) || reverse.has(right.name)) {
+      return pairs.get(left.name) === right.name && reverse.get(right.name) === left.name;
+    }
+    pairs.set(left.name, right.name);
+    reverse.set(right.name, left.name);
+    return true;
+  }
+  if (left.type !== right.type || left.name !== right.name || left.arity !== right.arity) return false;
+  for (let i = 0; i < left.arity; i++) {
+    if (!variantTerms(left.args[i], leftEnv, right.args[i], rightEnv, pairs, reverse)) return false;
+  }
+  return true;
+}
+
+export function compareTerms(left, right) {
+  const rank = (term) => ({ [VAR]: 0, [NUMBER]: 1, [ATOM]: 2, [STRING]: 3, [COMPOUND]: 4 })[term.type];
+  left = deref(left, new Env());
+  right = deref(right, new Env());
+  const lr = rank(left);
+  const rr = rank(right);
+  if (lr !== rr) return lr < rr ? -1 : 1;
+  if (left.type === NUMBER) return compareNumberText(left.name, right.name);
+  if (left.type === VAR || left.type === ATOM || left.type === STRING) return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
+  if (left.name !== right.name) return left.name < right.name ? -1 : 1;
+  if (left.arity !== right.arity) return left.arity < right.arity ? -1 : 1;
+  for (let i = 0; i < left.arity; i++) {
+    const cmp = compareTerms(left.args[i], right.args[i]);
+    if (cmp) return cmp;
+  }
+  return 0;
+}
+
+export function isDecimalInteger(text) {
+  return /^-?\d+$/.test(text ?? '');
+}
+
+export function compareIntegerText(left, right) {
+  const a = BigInt(left);
+  const b = BigInt(right);
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+export function parseFiniteNumber(text) {
+  if (text == null || text === '') return null;
+  if (!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(text)) return null;
+  const n = Number(text);
+  return Number.isFinite(n) ? n : null;
+}
+
+export function numberTextFromDouble(value) {
+  if (!Number.isFinite(value)) return null;
+  if (Object.is(value, -0)) value = 0;
+  let text = Number(value).toPrecision(17);
+  if (text.includes('e') || text.includes('E')) {
+    text = text.replace(/(\.\d*?[1-9])0+(e[+-]?\d+)$/i, '$1$2').replace(/\.0+(e[+-]?\d+)$/i, '$1');
+  } else if (text.includes('.')) {
+    text = text.replace(/0+$/, '').replace(/\.$/, '');
+  }
+  if (!/[.eE]/.test(text)) text += '.0';
+  return text;
+}
+
+export function compareNumberText(left, right) {
+  if (isDecimalInteger(left) && isDecimalInteger(right)) return compareIntegerText(left, right);
+  const a = parseFiniteNumber(left);
+  const b = parseFiniteNumber(right);
+  if (a != null && b != null) return a < b ? -1 : a > b ? 1 : 0;
+  return left < right ? -1 : left > right ? 1 : 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [
@@ -25,6 +25,8 @@
     "eyeling.js",
     "index.js",
     "index.d.ts",
+    "browser.d.ts",
+    "eyelang.d.ts",
     "bin",
     "dist",
     "lib",
@@ -58,7 +60,10 @@
     "test:package": "node test/package.test.js",
     "test": "node test/run.js",
     "preversion": "npm test",
-    "postversion": "git push origin HEAD --follow-tags"
+    "postversion": "git push origin HEAD --follow-tags",
+    "test:eyelang": "node test/eyelang.test.js && node test/eyelang/run-all.mjs",
+    "test:eyelang:integration": "node test/eyelang.test.js",
+    "test:eyelang:corpus": "node test/eyelang/run-all.mjs"
   },
   "dependencies": {
     "@rdfjs/types": "^2.0.1"
@@ -75,16 +80,21 @@
       "default": "./index.js"
     },
     "./browser": {
-      "types": "./index.d.ts",
+      "types": "./browser.d.ts",
       "default": "./dist/browser/index.mjs"
     },
     "./eyeling.js": "./eyeling.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./eyelang": {
+      "types": "./eyelang.d.ts",
+      "import": "./lib/eyelang/index.mjs",
+      "default": "./lib/eyelang/index.mjs"
+    }
   },
   "typesVersions": {
     "*": {
       "browser": [
-        "index.d.ts"
+        "browser.d.ts"
       ]
     }
   },