eyeling 1.32.0 → 1.33.0

package/lib/eyelang/builtins/sudoku.mjs

@@ -0,0 +1,141 @@
+// Sudoku-specific helpers used by the example suite.
+// The cover9/1 optimization prunes invalid row blocks early while leaving the declarative fallback available.
+import { deref, lexicalValue, listFromItems, numberTerm, properListItems, unify } from '../term.mjs';
+
+export const sudokuBuiltins = {
+  register(registry) {
+    registry.add('sudoku', 2, sudoku);
+    registry.add('cover9', 1, cover9, { deterministic: true, ready: cover9Ready });
+  }
+};
+
+
+function cover9Ready(goal, env) {
+  const items = properListItems(goal.args[0], env);
+  if (!items || items.length !== 9) return false;
+  for (const item of items) {
+    const text = lexicalValue(item, env);
+    if (!/^[1-9]$/.test(text ?? '')) return false;
+  }
+  return true;
+}
+
+function* cover9({ goal, env }) {
+  // cover9/1 succeeds exactly when a nine-cell block contains each digit once.
+  // The bit mask makes this a constant-time duplicate check after the list is ground.
+  const items = properListItems(goal.args[0], env);
+  if (!items || items.length !== 9) return;
+  let mask = 0;
+  for (const item of items) {
+    const text = lexicalValue(item, env);
+    if (!/^[1-9]$/.test(text ?? '')) return;
+    const bit = 1 << (Number(text) - 1);
+    if (mask & bit) return;
+    mask |= bit;
+  }
+  if (mask === 0x1ff) yield env;
+}
+
+function* sudoku({ solver, goal, env }) {
+  const cells = parseGrid(goal.args[0], env);
+  if (!cells) return;
+  const masks = initMasks(cells);
+  if (!masks) return;
+  for (const solved of search(cells, masks)) {
+    const next = env.clone();
+    if (unify(goal.args[1], solutionTerm(solved), next)) yield next;
+    if (solver.solutionsSeen >= solver.solutionLimit) return;
+  }
+}
+
+function parseGrid(term, env) {
+  const resolved = deref(term, env);
+  if (['atom', 'string', 'number'].includes(resolved.type)) return parseGridString(resolved.name);
+  const rows = properListItems(term, env);
+  if (!rows || rows.length !== 9) return null;
+  const cells = [];
+  for (const row of rows) {
+    const cols = properListItems(row, env);
+    if (!cols || cols.length !== 9) return null;
+    for (const cell of cols) {
+      const text = lexicalValue(cell, env);
+      if (!/^\d+$/.test(text ?? '')) return null;
+      const value = Number(text);
+      if (value < 0 || value > 9) return null;
+      cells.push(value);
+    }
+  }
+  return cells;
+}
+
+function parseGridString(text) {
+  if (!text || text.length !== 81) return null;
+  const cells = [];
+  for (const ch of text) {
+    if (ch === '.' || ch === '_') cells.push(0);
+    else if (ch >= '0' && ch <= '9') cells.push(Number(ch));
+    else return null;
+  }
+  return cells;
+}
+
+function initMasks(cells) {
+  const row = Array(9).fill(0), col = Array(9).fill(0), box = Array(9).fill(0);
+  for (let i = 0; i < 81; i++) {
+    const value = cells[i];
+    if (value === 0) continue;
+    const r = Math.floor(i / 9), c = i % 9, b = Math.floor(r / 3) * 3 + Math.floor(c / 3);
+    const bit = 1 << (value - 1);
+    if ((row[r] & bit) || (col[c] & bit) || (box[b] & bit)) return null;
+    row[r] |= bit; col[c] |= bit; box[b] |= bit;
+  }
+  return { row, col, box };
+}
+
+function popcount(mask) {
+  let n = 0;
+  while (mask) { n += mask & 1; mask >>= 1; }
+  return n;
+}
+
+function* search(cells, masks) {
+  // Choose the empty cell with the fewest legal candidates. This MRV heuristic
+  // is the main reason the compiled sudoku/2 helper stays fast.
+  const all = 0x1ff;
+  let best = -1, bestCandidates = 0, bestCount = 10;
+  for (let i = 0; i < 81; i++) {
+    if (cells[i] !== 0) continue;
+    const r = Math.floor(i / 9), c = i % 9, b = Math.floor(r / 3) * 3 + Math.floor(c / 3);
+    const candidates = all & ~(masks.row[r] | masks.col[c] | masks.box[b]);
+    const count = popcount(candidates);
+    if (count === 0) return;
+    if (count < bestCount) {
+      best = i; bestCandidates = candidates; bestCount = count;
+      if (count === 1) break;
+    }
+  }
+  if (best < 0) {
+    yield cells.slice();
+    return;
+  }
+  const r = Math.floor(best / 9), c = best % 9, b = Math.floor(r / 3) * 3 + Math.floor(c / 3);
+  for (let value = 1; value <= 9; value++) {
+    const bit = 1 << (value - 1);
+    if (!(bestCandidates & bit)) continue;
+    cells[best] = value;
+    masks.row[r] |= bit; masks.col[c] |= bit; masks.box[b] |= bit;
+    yield* search(cells, masks);
+    masks.box[b] &= ~bit; masks.col[c] &= ~bit; masks.row[r] &= ~bit;
+    cells[best] = 0;
+  }
+}
+
+function solutionTerm(cells) {
+  const rows = [];
+  for (let r = 0; r < 9; r++) {
+    const items = [];
+    for (let c = 0; c < 9; c++) items.push(numberTerm(cells[r * 9 + c]));
+    rows.push(listFromItems(items));
+  }
+  return listFromItems(rows);
+}

package/lib/eyelang/cli.mjs

@@ -0,0 +1,192 @@
+// Command-line interface for eyelang.
+// It loads programs from files, URLs, or stdin, then materializes derived output predicates.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+let engineModule = null;
+let explanationModule = null;
+
+export async function main(argv) {
+  if (argv.length === 0) {
+    await usage(process.stdout);
+    return;
+  }
+
+  const options = {
+    files: [],
+    proof: false,
+    stats: false,
+    version: false,
+    inputFormat: 'auto',
+  };
+
+  let endOptions = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (!endOptions && arg === '--') {
+      endOptions = true;
+    } else if (!endOptions && (arg === '--version' || arg === '-v')) {
+      options.version = true;
+    } else if (!endOptions && (arg === '--help' || arg === '-h')) {
+      await usage(process.stdout);
+      return;
+    } else if (!endOptions && (arg === '--proof' || arg === '-p')) {
+      options.proof = true;
+    } else if (!endOptions && (arg === '--stats' || arg === '-s')) {
+      options.stats = true;
+    } else if (!endOptions && (arg === '--rdf' || arg === '--rdf12')) {
+      options.inputFormat = 'rdf12';
+    } else if (!endOptions && arg === '--n3') {
+      options.inputFormat = 'n3';
+    } else if (!endOptions && arg === '--input-format') {
+      const value = argv[++i];
+      if (!value) throw new Error('--input-format needs a value');
+      options.inputFormat = value;
+    } else if (!endOptions && arg.startsWith('-') && arg !== '-') {
+      throw new Error(`unknown option: ${arg}`);
+    } else {
+      options.files.push(arg);
+    }
+  }
+
+  if (options.version) {
+    process.stdout.write(`eyelang ${await packageVersion()}\n`);
+    return;
+  }
+
+  if (options.files.length === 0) {
+    options.files.push('-');
+  }
+
+  const sourceParts = [];
+  let usedStdin = false;
+
+  for (const file of options.files) {
+    if (file === '-') {
+      if (usedStdin) throw new Error("stdin input '-' can only be used once");
+      usedStdin = true;
+      sourceParts.push({ text: await readStdin(), filename: '<stdin>' });
+    } else if (/^https?:\/\//.test(file)) {
+      const response = await fetch(file);
+      if (!response.ok) throw new Error(`could not fetch URL: ${file}`);
+      sourceParts.push({ text: await response.text(), filename: file });
+    } else {
+      sourceParts.push({ text: await fs.readFile(file, 'utf8'), filename: path.basename(file) || file });
+    }
+  }
+
+  const engine = await loadEngine();
+  const program = engine.Program.parseSources(sourceParts, { sourceMetadata: options.proof, markRecursive: options.proof, inputFormat: options.inputFormat });
+
+  await runDefault(engine, program, options);
+}
+
+async function loadEngine() {
+  if (engineModule == null) {
+    const [term, program, solver, registry] = await Promise.all([
+      import('./term.mjs'),
+      import('./program.mjs'),
+      import('./solver.mjs'),
+      import('./builtins/registry.mjs'),
+    ]);
+    engineModule = { ...term, ...program, ...solver, ...registry };
+  }
+  return engineModule;
+}
+
+async function loadExplanation() {
+  if (explanationModule == null) explanationModule = await import('./explain.mjs');
+  return explanationModule;
+}
+
+async function runDefault(engine, program, options) {
+  const goals = program.materializationGoals();
+  const materializedKeys = new Set(goals.map((goal) => `${goal.name}/${goal.arity}`));
+  const facts = program.sourceFactLines(materializedKeys);
+  const lines = new Set();
+  let lastStats = null;
+  const registry = engine.getDefaultRegistry();
+  const explanation = options.proof ? await loadExplanation() : null;
+
+  for (const goal of goals) {
+    const solver = new engine.Solver(program, { registry });
+
+    for (const env of solver.solve([goal], new engine.Env(), 0)) {
+      if (!engine.termIsGround(goal, env)) continue;
+
+      const line = `${engine.termToString(goal, env, true)}.\n`;
+      if (facts.has(line) || lines.has(line)) continue;
+
+      lines.add(line);
+
+      process.stdout.write(line);
+      if (options.proof) writeExplanation(explanation, program, engine.copyResolved(goal, env), registry);
+    }
+
+    lastStats = solver.stats;
+  }
+
+  if (options.stats && lastStats) printStats(lastStats);
+}
+
+function writeExplanation(explanation, program, resolved, registry) {
+  const proof = explanation.whyProof(program, resolved, { registry });
+  process.stdout.write(proof.text);
+  if (!proof.ok) process.stdout.write(explanation.whyNoProof(resolved));
+}
+
+async function usage(stream) {
+  stream.write(`eyelang ${await packageVersion()}
+
+Usage:
+  eyelang [options] [file-or-url.pl|- ...]
+
+Input:
+  file-or-url.pl        Read an eyelang program from a local file or http(s) URL.
+  -                     Read an eyelang program from standard input.
+
+Options:
+  -h, --help            Show this help text and exit.
+  -p, --proof           Enable proof explanations.
+  -s, --stats           Print solver statistics to stderr after execution.
+  --rdf, --rdf12        Read input as RDF 1.2 Turtle/N-Triples compatibility syntax.
+  --n3                  Read input as Notation3 rule compatibility syntax.
+  --input-format FORMAT Use eyelang, auto, rdf12, turtle, nt, or n3.
+  -v, --version         Show the package version and exit.
+  --                    Stop option parsing; following arguments are treated as files.
+`);
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+function printStats(stats) {
+  process.stderr.write('eyelang stats:\n');
+  for (const [key, value] of Object.entries(stats)) {
+    process.stderr.write(`  ${key}: ${value}\n`);
+  }
+}
+
+async function packageVersion() {
+  try {
+    const text = await fs.readFile(new URL('../../package.json', import.meta.url), 'utf8');
+    const pkg = JSON.parse(text);
+    if (pkg && typeof pkg.version === 'string' && pkg.version) return pkg.version;
+  } catch (_) {
+    // Fall through to a stable marker if package metadata is unavailable.
+  }
+
+  return 'unknown';
+}

package/lib/eyelang/explain.mjs

@@ -0,0 +1,324 @@
+// eyelang proof output helpers.
+// The explanation printer replays a successful goal against the program and emits
+// ordinary eyelang facts with nested proof terms.  Explanations are therefore both
+// human-readable and machine-readable.
+import { COMPOUND, Env, Term, VAR, deref, flattenConjunction, freshTerm, termToString, unify, variantTerms } from './term.mjs';
+import { selectClauseCandidates } from './program.mjs';
+import { createDefaultRegistry } from './builtins/registry.mjs';
+import { Solver, nextFreshId } from './solver.mjs';
+
+export function whyProof(program, goal, options = {}) {
+  const maxDepth = options.maxDepth ?? 256;
+  const registry = options.registry ?? createDefaultRegistry();
+  const env = options.env ?? new Env();
+  for (const proof of proveGoalAll(program, goal, env, 0, maxDepth, registry, [])) {
+    return { ok: true, text: renderWhyFacts(goal, proof.node, proof.env) };
+  }
+  return { ok: false, text: '' };
+}
+
+export function whyNoProof(goal) {
+  return renderWhyNoProof(goal);
+}
+
+// Kept for embedders that already import explainProof.  The CLI exposes machine-readable output through whyProof.
+export function explainProof(program, goal, options = {}) {
+  return whyProof(program, goal, options);
+}
+
+function* proveGoalAll(program, goal, env, depth, maxDepth, registry, active) {
+  if (depth > maxDepth) return;
+
+  if (goal.type === COMPOUND && goal.name === ',' && goal.arity === 2) {
+    for (const proved of proveGoalsAll(program, flattenConjunction(goal), env, depth + 1, maxDepth, registry, active)) {
+      yield {
+        env: proved.env,
+        node: {
+          goal: resolveForProof(goal, proved.env),
+          method: 'conjunction',
+          sourceHead: null,
+          sourceBody: flattenConjunction(goal),
+          bindings: [],
+          children: proved.children,
+        },
+      };
+    }
+    return;
+  }
+
+  const builtin = builtinDefinition(program, goal, env, registry);
+  if (builtin.handled) {
+    for (const next of builtinEnvs(builtin.def, builtin.solver, goal, env)) {
+      const proofEnv = next.clone ? next.clone() : next;
+      yield {
+        env: proofEnv,
+        node: {
+          goal: resolveForProof(goal, proofEnv),
+          method: builtinMethod(goal),
+          sourceHead: resolveForProof(goal, proofEnv),
+          sourceBody: [],
+          bindings: [],
+          children: builtinChildren(program, goal, proofEnv, depth + 1, maxDepth, registry, active),
+        },
+      };
+    }
+    return;
+  }
+
+  if (goal.type !== COMPOUND) return;
+
+  const group = program.findGroup(goal.name, goal.arity);
+  if (!group) return;
+  if (!group.memoized && activeVariant(goal, env, active)) return;
+
+  const candidates = selectClauseCandidates(group, goal, env);
+  for (const pass of [candidates.primary, candidates.fallback]) {
+    for (const clause of pass) {
+      const id = nextFreshId();
+      const freshHead = freshTerm(clause.head, id);
+      const freshBody = clause.body.map((term) => freshTerm(term, id));
+      const next = env.clone();
+      if (!unify(goal, freshHead, next)) continue;
+
+      const substitutions = collectClauseSubstitutions(clause, freshHead, freshBody);
+      const bindings = resolvedSubstitutions(substitutions, next);
+
+      if (freshBody.length === 0) {
+        yield {
+          env: next,
+          node: {
+            goal: resolveForProof(goal, next),
+            method: sourceMethod(clause, 'fact'),
+            sourceHead: clause.head,
+            sourceBody: [],
+            bindings,
+            children: [],
+          },
+        };
+        continue;
+      }
+
+      let activePushed = true;
+      active.push({ goal, env });
+      try {
+        for (const proved of proveGoalsAll(program, freshBody, next, depth + 1, maxDepth, registry, active)) {
+          active.pop();
+          activePushed = false;
+          yield {
+            env: proved.env,
+            node: {
+              goal: resolveForProof(goal, proved.env),
+              method: sourceMethod(clause, 'rule'),
+              sourceHead: clause.head,
+              sourceBody: clause.body,
+              bindings: resolvedSubstitutions(substitutions, proved.env),
+              children: proved.children,
+            },
+          };
+          active.push({ goal, env });
+          activePushed = true;
+        }
+      } finally {
+        if (activePushed) active.pop();
+      }
+    }
+  }
+}
+
+function* proveGoalsAll(program, goals, env, depth, maxDepth, registry, active) {
+  if (goals.length === 0) {
+    yield { env: env.clone(), children: [] };
+    return;
+  }
+
+  const selectedIndex = selectReadyDeterministicBuiltin(goals, env, registry);
+  const goal = goals[selectedIndex];
+  const rest = selectedIndex === 0 ? goals.slice(1) : [...goals.slice(0, selectedIndex), ...goals.slice(selectedIndex + 1)];
+
+  for (const proved of proveGoalAll(program, goal, env, depth, maxDepth, registry, active)) {
+    for (const tail of proveGoalsAll(program, rest, proved.env, depth, maxDepth, registry, active)) {
+      const children = tail.children.slice();
+      children.splice(selectedIndex, 0, proved.node);
+      yield { env: tail.env, children };
+    }
+  }
+}
+
+function builtinDefinition(program, goal, env, registry) {
+  if (goal.type !== COMPOUND) return { handled: false, def: null, solver: null };
+  const def = registry.get(goal.name, goal.arity);
+  if (!def) return { handled: false, def: null, solver: null };
+
+  const solver = new Solver(program, { registry });
+  if (!builtinIsUsedForGoal(def, solver, goal, env)) return { handled: false, def: null, solver: null };
+  return { handled: true, def, solver };
+}
+
+function* builtinEnvs(def, solver, goal, env) {
+  for (const next of def.handler({ solver, goal, env })) yield next;
+}
+
+function builtinIsUsedForGoal(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 builtinChildren(program, goal, env, depth, maxDepth, registry, active) {
+  if (goal.type !== COMPOUND) return [];
+  if (goal.name === 'once' && goal.arity === 1) {
+    for (const proved of proveGoalAll(program, goal.args[0], env.clone(), depth, maxDepth, registry, active)) return [proved.node];
+  }
+  return [];
+}
+
+function activeVariant(goal, env, active) {
+  return active.some((entry) => variantTerms(goal, env, entry.goal, entry.env));
+}
+
+function sourceMethod(clause, kind) {
+  const source = clause.source ?? {};
+  return {
+    type: 'source',
+    kind,
+    filename: source.filename ?? '<input>',
+    clause: source.clause ?? ((clause.index ?? 0) + 1),
+  };
+}
+
+function builtinMethod(goal) {
+  return {
+    type: 'builtin',
+    name: goal.type === COMPOUND ? goal.name : 'goal',
+    arity: goal.type === COMPOUND ? goal.arity : 0,
+  };
+}
+
+function renderMethodTerm(method) {
+  if (method && method.type === 'source') return `${method.kind}(${quoteString(method.filename)}, clause(${method.clause}))`;
+  if (method && method.type === 'builtin') return `builtin(${quoteAtomText(method.name)}, ${method.arity})`;
+  return String(method);
+}
+
+function renderWhyFacts(answerGoal, rootNode, env) {
+  const answer = termToString(resolveForProof(answerGoal, env), new Env(), true);
+  return renderWhyTerm(answer, renderAbstractProofTerm(rootNode, 1));
+}
+
+function renderWhyNoProof(goal) {
+  const answer = termToString(resolveForProof(goal, new Env()), new Env(), true);
+  return renderWhyTerm(answer, `${indent(1)}no_proof`);
+}
+
+function renderWhyTerm(answer, proofTerm) {
+  return ['why(', `${indent(1)}${answer},`, proofTerm, ').', '', ''].join('\n');
+}
+
+function renderAbstractProofTerm(node, level) {
+  const goal = termToString(node.goal, new Env(), true);
+  const hasTail = node.bindings.length || node.children.length;
+  const lines = [
+    `${indent(level)}proof(`,
+    `${indent(level + 1)}goal(${goal}),`,
+    `${indent(level + 1)}by(${renderMethodTerm(node.method)})${hasTail ? ',' : ''}`,
+  ];
+
+  if (node.bindings.length) lines.push(`${indent(level + 1)}${renderBindingsTerm(node.bindings)}${node.children.length ? ',' : ''}`);
+  if (node.children.length) lines.push(renderUsesTerm(node.children, level + 1));
+
+  lines.push(`${indent(level)})`);
+  return lines.join('\n');
+}
+
+function renderUsesTerm(children, level) {
+  const lines = [`${indent(level)}uses([`];
+  for (let i = 0; i < children.length; i++) {
+    const item = renderAbstractProofTerm(children[i], level + 1);
+    lines.push(i === children.length - 1 ? item : withTrailingComma(item));
+  }
+  lines.push(`${indent(level)}])`);
+  return lines.join('\n');
+}
+
+function renderBindingsTerm(bindings) {
+  return `bindings(${renderProofListInline(bindings, binding => `binding(${quoteString(binding.name)}, ${termToString(binding.value, new Env(), true)})`)})`;
+}
+
+function renderProofListInline(items, renderItem) {
+  return `[${items.map(item => renderItem(item)).join(', ')}]`;
+}
+
+function withTrailingComma(text) {
+  const lines = String(text).split('\n');
+  lines[lines.length - 1] += ',';
+  return lines.join('\n');
+}
+
+function indent(level) {
+  return '  '.repeat(level);
+}
+
+function quoteAtomText(text) {
+  return termToString({ type: 'atom', name: String(text), args: [] }, new Env(), true);
+}
+
+function quoteString(value) {
+  return JSON.stringify(String(value));
+}
+
+function originalVariableName(name) {
+  return String(name).replace(/#\d+$/, '');
+}
+
+function resolveForProof(term, env) {
+  const resolved = deref(term, env);
+  if (resolved.type === VAR) return new Term(VAR, originalVariableName(resolved.name), []);
+  return new Term(resolved.type, resolved.name, resolved.args.map((arg) => resolveForProof(arg, env)));
+}
+
+function collectClauseSubstitutions(clause, freshHead, freshBody) {
+  const substitutions = [];
+  const seen = new Set();
+  collectSubstitutions(clause.head, freshHead, substitutions, seen);
+  for (let i = 0; i < clause.body.length && i < freshBody.length; i++) {
+    collectSubstitutions(clause.body[i], freshBody[i], substitutions, seen);
+  }
+  return substitutions;
+}
+
+function collectSubstitutions(original, fresh, substitutions, seen) {
+  if (!original || !fresh) return;
+  if (original.type === VAR) {
+    if (!seen.has(original.name)) {
+      seen.add(original.name);
+      substitutions.push({ name: original.name, fresh });
+    }
+    return;
+  }
+  if (original.type !== COMPOUND || fresh.type !== COMPOUND) return;
+  const arity = Math.min(original.arity, fresh.arity);
+  for (let i = 0; i < arity; i++) collectSubstitutions(original.args[i], fresh.args[i], substitutions, seen);
+}
+
+function resolvedSubstitutions(substitutions, env) {
+  const out = [];
+  for (const substitution of substitutions) {
+    const resolved = deref(substitution.fresh, env);
+    if (resolved.type === VAR) continue;
+    out.push({ name: substitution.name, value: resolveForProof(substitution.fresh, env) });
+  }
+  return out;
+}