eyeling 1.32.0 → 1.33.0

package/lib/builtins.js

@@ -8,6 +8,8 @@
 
 const {
   RDF_NS,
+  RDFS_NS,
+  OWL_NS,
   XSD_NS,
   CRYPTO_NS,
   MATH_NS,
@@ -1035,6 +1037,9 @@ const XSD_HEX_BINARY_DT = XSD_NS + 'hexBinary';
 const XSD_BASE64_BINARY_DT = XSD_NS + 'base64Binary';
 const XSD_ANY_URI_DT = XSD_NS + 'anyURI';
 const RDF_LANGSTRING_DT = RDF_NS + 'langString';
+const RDF_PLAIN_LITERAL_DT = RDF_NS + 'PlainLiteral';
+const RDF_XML_LITERAL_DT = RDF_NS + 'XMLLiteral';
+const RDFS_LITERAL_DT = RDFS_NS + 'Literal';
 
 const XSD_STRING_LIKE_DTS = new Set([
   XSD_STRING_DT,
@@ -1063,6 +1068,9 @@ const XSD_INTEGER_BOUNDS = new Map([
 
 const XSD_DATATYPE_BUILTIN_DTS = new Set([
   RDF_LANGSTRING_DT,
+  RDF_PLAIN_LITERAL_DT,
+  RDF_XML_LITERAL_DT,
+  RDFS_LITERAL_DT,
   XSD_STRING_DT,
   XSD_NS + 'normalizedString',
   XSD_NS + 'token',
@@ -1084,6 +1092,11 @@ const XSD_DATATYPE_BUILTIN_DTS = new Set([
 ]);
 
 
+const XSD_FLOAT_MAX_VALUE = 3.4028234663852886e38;
+const XSD_FLOAT_MIN_POSITIVE_VALUE = 1.401298464324817e-45;
+const XSD_DOUBLE_MAX_VALUE = Number.MAX_VALUE;
+const XSD_DOUBLE_MIN_POSITIVE_VALUE = Number.MIN_VALUE;
+
 // Integer-derived datatypes from XML Schema Part 2 (and commonly used ones).
 const XSD_INTEGER_DERIVED_DTS = new Set([
   XSD_INTEGER_DT,
@@ -1142,13 +1155,31 @@ function inferDatatypeForShorthandLexical(lex) {
 
 function extractLiteralLanguageTag(litVal) {
   if (typeof litVal !== 'string' || !literalHasLangTag(litVal)) return null;
-  const lastQuote = litVal.lastIndexOf('"');
+
+  let lastQuote;
+  let quoteLen;
+  if (litVal.startsWith('\"\"\"')) {
+    lastQuote = litVal.lastIndexOf('\"\"\"');
+    quoteLen = 3;
+  } else {
+    lastQuote = litVal.lastIndexOf('"');
+    quoteLen = 1;
+  }
+
   if (lastQuote < 0) return null;
-  const after = lastQuote + 1;
+  const after = lastQuote + quoteLen;
   if (after >= litVal.length || litVal[after] !== '@') return null;
   const tag = litVal.slice(after + 1);
-  if (!/^[A-Za-z]+(?:-[A-Za-z0-9]+)*(?:--(?:ltr|rtl))?$/.test(tag)) return null;
-  return tag;
+  if (!isValidLanguageTag(tag, true)) return null;
+  return tag.toLowerCase();
+}
+
+function isValidLanguageTag(tag, allowDirectionalSuffix) {
+  if (typeof tag !== 'string') return false;
+  const pattern = allowDirectionalSuffix
+    ? /^[A-Za-z]{1,8}(?:-[A-Za-z0-9]{1,8})*(?:--(?:ltr|rtl))?$/
+    : /^[A-Za-z]{1,8}(?:-[A-Za-z0-9]{1,8})*$/;
+  return pattern.test(tag);
 }
 
 function literalLexicalValue(litVal) {
@@ -1207,17 +1238,18 @@ function canonicalFloatDoubleLex(n) {
 }
 
 function parseStringLikeDatatypeValue(lexical, dt) {
-  let value = String(lexical);
+  const value = String(lexical);
 
   if (dt === XSD_NS + 'normalizedString') {
-    value = value.replace(/[\t\n\r]/g, ' ');
+    if (/[\t\n\r]/.test(value)) return null;
   } else if (dt !== XSD_STRING_DT) {
-    value = value.replace(/[\t\n\r ]+/g, ' ').trim();
+    // String-derived datatypes with whitespace facet collapse are considered
+    // lexically valid only when the spelling is already in collapsed form.
+    if (/[\t\n\r]/.test(value) || /^ | $/.test(value) || / {2,}/.test(value)) return null;
   }
 
   if (dt === XSD_NS + 'language') {
-    if (!/^[A-Za-z]{1,8}(?:-[A-Za-z0-9]{1,8})*$/.test(value)) return null;
-    value = value.toLowerCase();
+    if (!isValidLanguageTag(value, false)) return null;
   } else if (dt === XSD_NS + 'Name') {
     if (!/^[:_\p{L}][:_\p{L}\p{N}.\-\u00B7\u0300-\u036F\u203F-\u2040]*$/u.test(value)) return null;
   } else if (dt === XSD_NS + 'NCName') {
@@ -1229,9 +1261,51 @@ function parseStringLikeDatatypeValue(lexical, dt) {
   return {
     family: 'string',
     dt,
-    value,
-    canonicalLex: value,
-    canonicalLiteral: makeDatatypeTypedLiteral(value, dt),
+    value: dt === XSD_NS + 'language' ? value.toLowerCase() : value,
+    canonicalLex: dt === XSD_NS + 'language' ? value.toLowerCase() : value,
+    canonicalLiteral: makeDatatypeTypedLiteral(dt === XSD_NS + 'language' ? value.toLowerCase() : value, dt),
+    comparable: true,
+  };
+}
+
+function parsePlainLiteralDatatypeValue(lexical) {
+  const parsed = splitPlainLiteralLexical(lexical);
+  if (!parsed) return null;
+  const canonicalLex = `${parsed.text}@${parsed.lang}`;
+  return {
+    family: 'plainLiteral',
+    dt: RDF_PLAIN_LITERAL_DT,
+    value: parsed.text,
+    lang: parsed.lang,
+    canonicalLex,
+    canonicalLiteral: makeDatatypeTypedLiteral(canonicalLex, RDF_PLAIN_LITERAL_DT),
+    comparable: true,
+  };
+}
+
+function splitPlainLiteralLexical(lexical) {
+  const s = String(lexical);
+  const at = s.lastIndexOf('@');
+  // rdf:PlainLiteral lexical forms encode the literal as text + "@" +
+  // language-tag.  The language tag may be empty, e.g. "abc@".
+  // A lexical with no separator at all, e.g. "abc", is ill-typed.
+  if (at < 0) return null;
+  const text = s.slice(0, at);
+  const lang = s.slice(at + 1);
+  if (lang !== '' && !isValidLanguageTag(lang, false)) return null;
+  return { text, lang: lang.toLowerCase() };
+}
+
+function parseXmlLiteralDatatypeValue(lexical) {
+  const s = String(lexical);
+  if (!isWellFormedXmlFragment(s)) return null;
+  const canonicalLex = s.trim();
+  return {
+    family: 'xmlLiteral',
+    dt: RDF_XML_LITERAL_DT,
+    value: canonicalLex,
+    canonicalLex,
+    canonicalLiteral: makeDatatypeTypedLiteral(canonicalLex, RDF_XML_LITERAL_DT),
     comparable: true,
   };
 }
@@ -1319,6 +1393,11 @@ function parseFloatDoubleDatatypeValue(lexical, dt) {
   const special = parseXsdFloatSpecialLex(s);
   const value = special !== null ? special : Number(s);
   if (Number.isNaN(value) && s !== 'NaN') return null;
+  if (Number.isFinite(value)) {
+    const abs = Math.abs(value);
+    if (dt === XSD_FLOAT_DT && abs > 0 && (abs > XSD_FLOAT_MAX_VALUE || abs < XSD_FLOAT_MIN_POSITIVE_VALUE)) return null;
+    if (dt === XSD_DOUBLE_DT && abs > 0 && (abs > XSD_DOUBLE_MAX_VALUE || abs < XSD_DOUBLE_MIN_POSITIVE_VALUE)) return null;
+  }
   const canonicalLex = canonicalFloatDoubleLex(value);
   return {
     family: 'numeric',
@@ -1408,7 +1487,11 @@ function parseBinaryDatatypeValue(lexical, dt) {
 
 function parseAnyUriDatatypeValue(lexical) {
   const value = String(lexical);
-  if (/[\u0000-\u001F\u007F]/.test(value)) return null;
+  if (/[^\u0021-\u007E]/.test(value) || /[<>"{}|\\^`]/.test(value)) return null;
+  for (let i = 0; i < value.length; i += 1) {
+    if (value[i] === '%' && !/^[0-9A-Fa-f]{2}$/.test(value.slice(i + 1, i + 3))) return null;
+  }
+  if (!isValidIriReferenceLexical(value)) return null;
   return {
     family: 'anyURI',
     dt: XSD_ANY_URI_DT,
@@ -1419,6 +1502,116 @@ function parseAnyUriDatatypeValue(lexical) {
   };
 }
 
+function isValidIriReferenceLexical(value) {
+  // Minimal RFC 3987/3986 structural check for IRI references.  In
+  // particular, a relative reference may not start with a colon-bearing first
+  // path segment such as ":abc"; this is the OWL 2 RL anyURI illtyped case.
+  // Empty references and fragment-only references are allowed.
+  const s = String(value);
+  if (s === '') return true;
+  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(s)) return true; // absolute scheme
+  if (s.startsWith('//') || s.startsWith('/') || s.startsWith('?') || s.startsWith('#')) return true;
+  const cut = s.search(/[/?#]/);
+  const firstSegment = cut < 0 ? s : s.slice(0, cut);
+  return !firstSegment.includes(':');
+}
+
+function isWellFormedXmlFragment(input) {
+  const source = String(input).trim();
+  if (!source) return false;
+  const stack = [];
+  let seenElement = false;
+  let position = 0;
+
+  while (position < source.length) {
+    const open = source.indexOf('<', position);
+    if (open < 0) return stack.length === 0 && isValidXmlText(source.slice(position)) && seenElement;
+    if (!isValidXmlText(source.slice(position, open))) return false;
+
+    if (source.startsWith('<!--', open)) {
+      const close = source.indexOf('-->', open + 4);
+      if (close < 0 || source.slice(open + 4, close).includes('--')) return false;
+      position = close + 3;
+      continue;
+    }
+
+    if (source.startsWith('<![CDATA[', open)) {
+      const close = source.indexOf(']]>', open + 9);
+      if (close < 0) return false;
+      position = close + 3;
+      continue;
+    }
+
+    if (source.startsWith('<?', open)) {
+      const close = source.indexOf('?>', open + 2);
+      if (close < 0) return false;
+      position = close + 2;
+      continue;
+    }
+
+    if (source.startsWith('</', open)) {
+      const close = source.indexOf('>', open + 2);
+      if (close < 0) return false;
+      const name = source.slice(open + 2, close).trim();
+      if (!isValidXmlName(name) || stack.pop() !== name) return false;
+      position = close + 1;
+      continue;
+    }
+
+    const close = findXmlTagEnd(source, open + 1);
+    if (close < 0) return false;
+    const raw = source.slice(open + 1, close);
+    const selfClosing = /\/\s*$/.test(raw);
+    const content = selfClosing ? raw.replace(/\/\s*$/, '').trim() : raw.trim();
+    const nameMatch = /^([^\s/>]+)/.exec(content);
+    if (!nameMatch || !isValidXmlName(nameMatch[1]) || !areValidXmlAttributes(content.slice(nameMatch[0].length))) return false;
+    seenElement = true;
+    if (!selfClosing) stack.push(nameMatch[1]);
+    position = close + 1;
+  }
+
+  return stack.length === 0 && seenElement;
+}
+
+function findXmlTagEnd(source, start) {
+  let quote = null;
+  for (let i = start; i < source.length; i += 1) {
+    const ch = source[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+    } else if (ch === '>') {
+      return i;
+    }
+  }
+  return -1;
+}
+
+function areValidXmlAttributes(source) {
+  let rest = String(source).trim();
+  const seen = new Set();
+  while (rest) {
+    const m = /^([A-Za-z_:\u0080-\uFFFF][A-Za-z0-9_.:\-\u0080-\uFFFF]*)\s*=\s*("[^"]*"|'[^']*')\s*/u.exec(rest);
+    if (!m || seen.has(m[1]) || !isValidXmlAttributeValue(m[2].slice(1, -1))) return false;
+    seen.add(m[1]);
+    rest = rest.slice(m[0].length).trim();
+  }
+  return true;
+}
+
+function isValidXmlAttributeValue(value) {
+  return !/[<]/.test(value) && isValidXmlText(value);
+}
+
+function isValidXmlText(value) {
+  return !/[<&]/.test(String(value).replace(/&(?:amp|lt|gt|quot|apos|#\d+|#x[0-9A-Fa-f]+);/g, ''));
+}
+
+function isValidXmlName(name) {
+  return /^[A-Za-z_:\u0080-\uFFFF][A-Za-z0-9_.:\-\u0080-\uFFFF]*$/u.test(name) && !/^xml$/i.test(name);
+}
+
 function isLeapYearBigInt(year) {
   if (year % 400n === 0n) return true;
   if (year % 100n === 0n) return false;
@@ -1575,11 +1768,33 @@ function parseLangStringDatatypeValue(t, lexical) {
   };
 }
 
+function literalTermDatatypeKey(t) {
+  return `${literalLexicalValue(t.value)}^^${literalDatatypeIri(t) || ''}`;
+}
+
 function parseDatatypeValueForDatatype(t, dt) {
   if (!(t instanceof Literal) || typeof dt !== 'string' || !isSupportedDatatypeIri(dt)) return null;
+
+  if (dt === RDFS_LITERAL_DT) {
+    const ownDt = literalDatatypeIri(t);
+    if (ownDt === null || !isSupportedDatatypeIri(ownDt)) return null;
+    const ownValue = parseDatatypeValueForDatatype(t, ownDt);
+    if (!ownValue) return null;
+    return {
+      family: 'literal',
+      dt: RDFS_LITERAL_DT,
+      value: literalTermDatatypeKey(t),
+      canonicalLex: literalLexicalValue(t.value),
+      canonicalLiteral: t,
+      comparable: false,
+    };
+  }
+
   const lexical = literalLexicalValue(t.value);
 
   if (dt === RDF_LANGSTRING_DT) return parseLangStringDatatypeValue(t, lexical);
+  if (dt === RDF_PLAIN_LITERAL_DT) return parsePlainLiteralDatatypeValue(lexical);
+  if (dt === RDF_XML_LITERAL_DT) return parseXmlLiteralDatatypeValue(lexical);
   if (literalHasLangTag(t.value)) return null;
   if (XSD_STRING_LIKE_DTS.has(dt)) return parseStringLikeDatatypeValue(lexical, dt);
   if (dt === XSD_BOOLEAN_DT) return parseBooleanDatatypeValue(lexical);
@@ -1605,10 +1820,11 @@ function compareDecimalExactValues(a, b) {
 
 function datatypeValuesSame(a, b) {
   if (!a || !b || !a.comparable || !b.comparable) return false;
-  if (a.family === 'langString' || b.family === 'langString') {
+  if (a.family === 'langString' || b.family === 'langString' || a.family === 'plainLiteral' || b.family === 'plainLiteral') {
     return a.family === b.family && a.value === b.value && a.lang === b.lang;
   }
   if (a.family === 'string' && b.family === 'string') return a.value === b.value;
+  if (a.family === 'xmlLiteral' && b.family === 'xmlLiteral') return a.value === b.value;
   if (a.family === 'boolean' && b.family === 'boolean') return a.value === b.value;
   if (a.family === 'anyURI' && b.family === 'anyURI') return a.value === b.value;
   if (a.family === 'binary' && b.family === 'binary') {
@@ -1635,7 +1851,9 @@ function datatypeValuesSame(a, b) {
 function datatypeValuesComparable(a, b) {
   if (!a || !b || !a.comparable || !b.comparable) return false;
   if (a.family === 'dateTime' && b.family === 'dateTime' && a.hasTimezone !== b.hasTimezone) return false;
+  if (a.family === 'numeric' && b.family === 'numeric') return true;
   if (a.family === 'langString' || b.family === 'langString') return a.family === b.family;
+  if (a.family === 'plainLiteral' || b.family === 'plainLiteral') return a.family === b.family;
   if (a.family === 'string' || b.family === 'string') return a.family === b.family;
   return a.family === b.family;
 }
@@ -1659,6 +1877,17 @@ function evalDatatypeInspectionBuiltin(g, subst, kind) {
     const dt = literalDatatypeIri(g.s);
     if (dt === null) return [];
     valueTerm = internIri(dt);
+    const out = evalBindBuiltinObject(g.o, valueTerm, subst);
+
+    // OWL 2 RL datatype rules often need common string literals to also
+    // participate in generic literal comparisons, while application rules still
+    // ask for their precise datatype explicitly.  When the datatype output is
+    // unbound, expose rdfs:Literal as an additional super-datatype answer for
+    // xsd:string and rdf:langString; bound-object calls remain strictly exact.
+    if (g.o instanceof Var && (dt === XSD_STRING_DT || dt === RDF_LANGSTRING_DT)) {
+      out.push(...evalBindBuiltinObject(g.o, internIri(RDFS_LITERAL_DT), subst));
+    }
+    return out;
   } else if (kind === 'lexicalForm') {
     valueTerm = makeStringLiteral(literalLexicalValue(g.s.value));
   } else if (kind === 'language') {
@@ -1727,6 +1956,57 @@ function evalDatatypeValueComparisonBuiltin(g, subst, same) {
   return [];
 }
 
+function evalOwlSameAsBuiltin(g, subst, facts, maxResults) {
+  const out = [];
+  const seen = new Set();
+  const limit = typeof maxResults === 'number' && maxResults > 0 ? maxResults : Infinity;
+
+  function addPair(left, right) {
+    if (out.length >= limit) return true;
+    const key = `${termFastKey ? termFastKey(left) : termToN3(left)} ${termFastKey ? termFastKey(right) : termToN3(right)}`;
+    if (seen.has(key)) return false;
+    let s2 = unifyTerm(g.s, left, subst);
+    if (s2 === null) return false;
+    s2 = unifyTerm(g.o, right, s2);
+    if (s2 === null) return false;
+    seen.add(key);
+    out.push(s2);
+    return out.length >= limit;
+  }
+
+  function addReflexive(term) {
+    return addPair(term, term);
+  }
+
+  const sameAsIri = OWL_NS + 'sameAs';
+  const differentFromIri = OWL_NS + 'differentFrom';
+
+  for (const tr of facts || []) {
+    if (tr && tr.p instanceof Iri && tr.p.value === sameAsIri) {
+      if (addPair(tr.s, tr.o)) return out;
+    }
+  }
+
+  // owl:sameAs is reflexive.  Avoid enumerating the entire active term universe
+  // for fully-unbound goals; only add the reflexive pairs that are immediately
+  // needed to detect explicit self-diversity (?x owl:differentFrom ?x).
+  if (!(g.s instanceof Var) && !(g.o instanceof Var)) {
+    if (termsEqual(g.s, g.o)) addReflexive(g.s);
+  } else if (!(g.s instanceof Var)) {
+    addReflexive(g.s);
+  } else if (!(g.o instanceof Var)) {
+    addReflexive(g.o);
+  } else {
+    for (const tr of facts || []) {
+      if (tr && tr.p instanceof Iri && tr.p.value === differentFromIri && termsEqual(tr.s, tr.o)) {
+        if (addReflexive(tr.s)) return out;
+      }
+    }
+  }
+
+  return out;
+}
+
 // ===========================================================================
 // Math builtin helpers
 // ===========================================================================
@@ -2866,6 +3146,8 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
   const pv = iriValue(g.p);
   if (pv === null) return null;
 
+  if (pv === OWL_NS + 'sameAs') return evalOwlSameAsBuiltin(g, subst, facts, maxResults);
+
   // Super restricted mode: disable *all* builtins except => / <= (log:implies / log:impliedBy)
   if (typeof getSuperRestrictedMode === 'function' && getSuperRestrictedMode()) {
     const allow1 = LOG_NS + 'implies';
@@ -5208,6 +5490,7 @@ function isBuiltinPred(p) {
   }
 
   if (__customBuiltinHandlers.has(v)) return true;
+  if (v === OWL_NS + 'sameAs') return true;
 
   return (
     v.startsWith(CRYPTO_NS) ||

package/lib/cli.js

@@ -805,6 +805,7 @@ async function main() {
       `Options:\n` +
       `  -a, --ast                    Print parsed AST as JSON and exit.\n` +
       `      --builtin <module.js>    Load a custom builtin module (repeatable).\n` +
+      `      --engine <n3|eyelang>    Select the N3 engine (default) or eyelang engine.\n` +
       `  -d, --deterministic-skolem   Make log:skolem stable across reasoning runs.\n` +
       `  -e, --enforce-https          Rewrite http:// IRIs to https:// for log dereferencing builtins.\n` +
       `  -h, --help                   Show this help and exit.\n` +

package/lib/eyelang/bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+'use strict';
+
+import('./cli.mjs').then(({ main }) => main(process.argv.slice(2))).catch((error) => {
+  console.error(`eyelang: ${error && error.message ? error.message : String(error)}`);
+  process.exit(1);
+});

package/lib/eyelang/builtins/aggregation.mjs

@@ -0,0 +1,81 @@
+// Aggregation builtins that run a inner goal and collect, count, sum, or select the best answers.
+// Each handler clones the solver so the inner goal can enumerate independently of the outer goal.
+import { compareTerms, copyResolved, isDecimalInteger, lexicalValue, listFromItems, numberTerm, numberTextFromDouble, parseFiniteNumber, unify } from '../term.mjs';
+
+export const aggregationBuiltins = {
+  register(registry) {
+    registry.add('findall', 3, findall);
+    registry.add('countall', 2, countall);
+    registry.add('sumall', 3, sumall);
+    registry.add('aggregate_min', 5, aggregateBest(true));
+    registry.add('aggregate_max', 5, aggregateBest(false));
+  }
+};
+
+function* findall({ solver, goal, env }) {
+  const [template, innerGoal, bag] = goal.args;
+  const collector = solver.cloneForInnerGoal(10000000);
+  const collected = [];
+  for (const answerEnv of collector.solve([innerGoal], env.clone(), 0)) collected.push(copyResolved(template, answerEnv));
+  const next = env.clone();
+  if (unify(bag, listFromItems(collected), next)) yield next;
+}
+
+function* countall({ solver, goal, env }) {
+  const [innerGoal, count] = goal.args;
+  const collector = solver.cloneForInnerGoal(10000000);
+  let n = 0;
+  for (const _ of collector.solve([innerGoal], env.clone(), 0)) n++;
+  const next = env.clone();
+  if (unify(count, numberTerm(n), next)) yield next;
+}
+
+function* sumall({ solver, goal, env }) {
+  const [template, innerGoal, sum] = goal.args;
+  const collector = solver.cloneForInnerGoal(10000000);
+  let intSum = 0n;
+  let floatMode = false;
+  let floatSum = 0;
+  for (const answerEnv of collector.solve([innerGoal], env.clone(), 0)) {
+    const text = lexicalValue(template, answerEnv);
+    if (text == null) return;
+    if (!floatMode && isDecimalInteger(text)) intSum += BigInt(text);
+    else {
+      const value = parseFiniteNumber(text);
+      if (value == null) return;
+      if (!floatMode) { floatSum = Number(intSum); floatMode = true; }
+      floatSum += value;
+    }
+  }
+  const result = floatMode ? numberTextFromDouble(floatSum) : intSum.toString();
+  const next = env.clone();
+  if (unify(sum, numberTerm(result), next)) yield next;
+}
+
+function aggregateBest(wantMin) {
+  return function* ({ solver, goal, env }) {
+    const [keyTemplate, valueTemplate, innerGoal, bestKey, bestValue] = goal.args;
+    const collector = solver.cloneForInnerGoal(10000000);
+    let has = false;
+    let key = null;
+    let value = null;
+    for (const answerEnv of collector.solve([innerGoal], env.clone(), 0)) {
+      const candidateKey = copyResolved(keyTemplate, answerEnv);
+      const candidateValue = copyResolved(valueTemplate, answerEnv);
+      if (!has) {
+        has = true;
+        key = candidateKey;
+        value = candidateValue;
+      } else {
+        const cmp = compareTerms(candidateKey, key);
+        if ((wantMin && cmp < 0) || (!wantMin && cmp > 0)) {
+          key = candidateKey;
+          value = candidateValue;
+        }
+      }
+    }
+    if (!has) return;
+    const next = env.clone();
+    if (unify(bestKey, key, next) && unify(bestValue, value, next)) yield next;
+  };
+}

package/lib/eyelang/builtins/alphametic.mjs

@@ -0,0 +1,144 @@
+// Reusable alphametic addition solver.
+// It evaluates column constraints right-to-left, so examples such as
+// SEND+MORE=MONEY and DONALD+GERALD=ROBERT do not need to express digit search
+// with many relational select/3 and arithmetic goals.
+import { atom, deref, listFromItems, numberTerm, properListItems, unify } from '../term.mjs';
+
+export const alphameticBuiltins = {
+  register(registry) {
+    registry.add('alphametic_sum', 5, alphameticSum, {
+      fallbackWhenNotReady: true,
+      ready: alphameticReady,
+    });
+  }
+};
+
+function alphameticReady(goal, env) {
+  return atomList(goal.args[0], env) !== null && wordList(goal.args[1], env) !== null && atomList(goal.args[2], env) !== null;
+}
+
+function* alphameticSum({ goal, env }) {
+  const letters = atomList(goal.args[0], env);
+  const addends = wordList(goal.args[1], env);
+  const result = atomList(goal.args[2], env);
+  if (!letters || !addends || !result || letters.length > 10 || addends.length === 0) return;
+
+  const letterSet = new Set(letters);
+  for (const word of [...addends, result]) for (const letter of word) if (!letterSet.has(letter)) return;
+
+  const leading = new Set();
+  for (const word of [...addends, result]) if (word.length > 1) leading.add(word[0]);
+  const maxLen = Math.max(result.length, ...addends.map((word) => word.length));
+  const assignment = new Map();
+  const used = Array(10).fill(false);
+
+  function canUse(letter, digit) {
+    return !used[digit] && !(digit === 0 && leading.has(letter));
+  }
+
+  function assignDigit(letter, digit) {
+    assignment.set(letter, digit);
+    used[digit] = true;
+  }
+
+  function unassignDigit(letter, digit) {
+    assignment.delete(letter);
+    used[digit] = false;
+  }
+
+  function* assignAddends(column, carry, index, sum) {
+    if (index >= addends.length) {
+      yield* finishColumn(column, sum);
+      return;
+    }
+    const word = addends[index];
+    const letter = word[word.length - 1 - column];
+    if (letter === undefined) {
+      yield* assignAddends(column, carry, index + 1, sum);
+      return;
+    }
+    const assigned = assignment.get(letter);
+    if (assigned !== undefined) {
+      yield* assignAddends(column, carry, index + 1, sum + assigned);
+      return;
+    }
+    for (let digit = 0; digit <= 9; digit++) {
+      if (!canUse(letter, digit)) continue;
+      assignDigit(letter, digit);
+      yield* assignAddends(column, carry, index + 1, sum + digit);
+      unassignDigit(letter, digit);
+    }
+  }
+
+  function* finishColumn(column, sum) {
+    const resultLetter = result[result.length - 1 - column];
+    const digit = sum % 10;
+    const nextCarry = Math.floor(sum / 10);
+    if (resultLetter === undefined) {
+      if (digit === 0) yield* solveColumn(column + 1, nextCarry);
+      return;
+    }
+    const assigned = assignment.get(resultLetter);
+    if (assigned !== undefined) {
+      if (assigned === digit) yield* solveColumn(column + 1, nextCarry);
+      return;
+    }
+    if (!canUse(resultLetter, digit)) return;
+    assignDigit(resultLetter, digit);
+    yield* solveColumn(column + 1, nextCarry);
+    unassignDigit(resultLetter, digit);
+  }
+
+  function* solveColumn(column, carry) {
+    if (column >= maxLen) {
+      if (carry !== 0) return;
+      if (assignment.size !== letters.length) return;
+      yield new Map(assignment);
+      return;
+    }
+    yield* assignAddends(column, carry, 0, carry);
+  }
+
+  for (const solution of solveColumn(0, 0)) {
+    const digitTerms = letters.map((letter) => numberTerm(String(solution.get(letter))));
+    const values = [...addends, result].map((word) => wordValue(word, solution));
+    const valueTerms = values.map((value) => numberTerm(String(value)));
+    const next = env.clone();
+    if (unify(goal.args[3], listFromItems(digitTerms), next) && unify(goal.args[4], listFromItems(valueTerms), next)) yield next;
+  }
+}
+
+function wordValue(word, assignment) {
+  let value = 0;
+  for (const letter of word) value = value * 10 + assignment.get(letter);
+  return value;
+}
+
+function atomList(term, env) {
+  const items = properListItems(term, env);
+  if (!items) return null;
+  const out = [];
+  for (const item of items) {
+    const text = atomKey(deref(item, env));
+    if (text == null) return null;
+    out.push(text);
+  }
+  return out;
+}
+
+function wordList(term, env) {
+  const items = properListItems(term, env);
+  if (!items) return null;
+  const out = [];
+  for (const item of items) {
+    const word = atomList(item, env);
+    if (!word) return null;
+    out.push(word);
+  }
+  return out;
+}
+
+function atomKey(term) {
+  if (term.type === 'atom' || term.type === 'string' || term.type === 'number') return term.name;
+  return null;
+}