eyeling 1.17.2 → 1.18.1

package/eyeling.js

@@ -9,6 +9,474 @@
   const __cache = Object.create(null);
 
   // ---- bundled modules ----
+  __modules["lib/builtin-sudoku.js"] = function(require, module, exports){
+'use strict';
+
+module.exports = function registerSudokuBuiltins(api) {
+  const { registerBuiltin, internLiteral, termToJsString, unifyTerm, terms } = api;
+  const { Var } = terms;
+
+  const SUDOKU_NS = 'http://example.org/sudoku-builtin#';
+  const __sudokuReportCache = new Map();
+  const __SUDOKU_ALL = 0x1ff;
+
+  function makeStringLiteral(str) {
+    return internLiteral(JSON.stringify(str));
+  }
+
+  function digitMask(v) {
+    return 1 << (v - 1);
+  }
+
+  function boxIndex(r, c) {
+    return Math.floor(r / 3) * 3 + Math.floor(c / 3);
+  }
+
+  function popcount(mask) {
+    let n = 0;
+    while (mask) {
+      mask &= mask - 1;
+      n += 1;
+    }
+    return n;
+  }
+
+  function maskToDigits(mask) {
+    const out = [];
+    for (let d = 1; d <= 9; d += 1) if (mask & digitMask(d)) out.push(d);
+    return out;
+  }
+
+  function formatBoard(cells) {
+    let out = '';
+    for (let r = 0; r < 9; r += 1) {
+      if (r > 0 && r % 3 === 0) out += '\n';
+      for (let c = 0; c < 9; c += 1) {
+        if (c > 0 && c % 3 === 0) out += '| ';
+        const v = cells[r * 9 + c];
+        out += v === 0 ? '. ' : `${String(v)} `;
+      }
+      out += '\n';
+    }
+    return out;
+  }
+
+  function parsePuzzle(input) {
+    const filtered = [];
+    for (const ch of input) {
+      if (/\s/.test(ch) || ch === '|' || ch === '+') continue;
+      filtered.push(ch);
+    }
+    if (filtered.length !== 81) {
+      return { error: `Expected exactly 81 cells after removing whitespace, but found ${filtered.length}.` };
+    }
+    const cells = new Array(81).fill(0);
+    for (let i = 0; i < 81; i += 1) {
+      const ch = filtered[i];
+      if (ch >= '1' && ch <= '9') cells[i] = ch.charCodeAt(0) - 48;
+      else if (ch === '0' || ch === '.' || ch === '_') cells[i] = 0;
+      else return { error: `Unexpected character '${ch}' at position ${i + 1}.` };
+    }
+    return { cells };
+  }
+
+  function attachMethods(state) {
+    state.place = function place(idx, value) {
+      if (this.cells[idx] !== 0) return this.cells[idx] === value;
+      const row = Math.floor(idx / 9);
+      const col = idx % 9;
+      const bx = boxIndex(row, col);
+      const bit = digitMask(value);
+      if (((this.rowUsed[row] | this.colUsed[col] | this.boxUsed[bx]) & bit) !== 0) return false;
+      this.cells[idx] = value;
+      this.rowUsed[row] |= bit;
+      this.colUsed[col] |= bit;
+      this.boxUsed[bx] |= bit;
+      return true;
+    };
+
+    state.candidates = function candidates(idx) {
+      const row = Math.floor(idx / 9);
+      const col = idx % 9;
+      const bx = boxIndex(row, col);
+      return __SUDOKU_ALL & ~(this.rowUsed[row] | this.colUsed[col] | this.boxUsed[bx]);
+    };
+
+    state.clone = function clone() {
+      return attachMethods({
+        cells: this.cells.slice(),
+        rowUsed: this.rowUsed.slice(),
+        colUsed: this.colUsed.slice(),
+        boxUsed: this.boxUsed.slice(),
+        moves: this.moves.slice(),
+      });
+    };
+
+    return state;
+  }
+
+  function stateFromPuzzle(cells) {
+    const state = attachMethods({
+      cells: new Array(81).fill(0),
+      rowUsed: new Array(9).fill(0),
+      colUsed: new Array(9).fill(0),
+      boxUsed: new Array(9).fill(0),
+      moves: [],
+    });
+
+    for (let idx = 0; idx < 81; idx += 1) {
+      const value = cells[idx];
+      if (value === 0) continue;
+      if (value < 1 || value > 9) {
+        return { error: `Cell ${idx + 1} contains ${value}, but only digits 1-9 or 0/. are allowed.` };
+      }
+      if (!state.place(idx, value)) {
+        const row = Math.floor(idx / 9) + 1;
+        const col = (idx % 9) + 1;
+        return { error: `The given clues already conflict at row ${row}, column ${col}.` };
+      }
+    }
+
+    return { state };
+  }
+
+  function summarizeMoves(moves, limit) {
+    if (!moves.length) return 'no placements were needed';
+    const parts = [];
+    for (const mv of moves.slice(0, limit)) {
+      const row = Math.floor(mv.index / 9) + 1;
+      const col = (mv.index % 9) + 1;
+      const mode = mv.forced ? 'forced' : 'guess';
+      parts.push(`r${row}c${col}=${mv.value}: ${mode}`);
+    }
+    if (moves.length > limit) parts.push(`… and ${moves.length - limit} more placements`);
+    return parts.join(', ');
+  }
+
+  function unitIsComplete(values) {
+    let seen = 0;
+    for (const v of values) {
+      if (v < 1 || v > 9) return false;
+      const bit = digitMask(v);
+      if (seen & bit) return false;
+      seen |= bit;
+    }
+    return seen === __SUDOKU_ALL;
+  }
+
+  function replayMovesAreLegal(puzzleCells, moves) {
+    const init = stateFromPuzzle(puzzleCells);
+    if (init.error) return false;
+    const state = init.state;
+    for (const mv of moves) {
+      if (state.cells[mv.index] !== 0) return false;
+      const maskNow = state.candidates(mv.index);
+      if (maskNow !== mv.candidatesMask) return false;
+      if ((maskNow & digitMask(mv.value)) === 0) return false;
+      if (mv.forced && popcount(maskNow) !== 1) return false;
+      if (!state.place(mv.index, mv.value)) return false;
+    }
+    return true;
+  }
+
+  function propagateSingles(state, stats) {
+    for (;;) {
+      let progress = false;
+      for (let idx = 0; idx < 81; idx += 1) {
+        if (state.cells[idx] !== 0) continue;
+        const mask = state.candidates(idx);
+        const count = popcount(mask);
+        if (count === 0) return false;
+        if (count === 1) {
+          const digit = maskToDigits(mask)[0];
+          state.moves.push({ index: idx, value: digit, candidatesMask: mask, forced: true });
+          if (!state.place(idx, digit)) return false;
+          stats.forcedMoves += 1;
+          progress = true;
+        }
+      }
+      if (!progress) return true;
+    }
+  }
+
+  function selectUnfilledCell(state) {
+    let best = null;
+    for (let idx = 0; idx < 81; idx += 1) {
+      if (state.cells[idx] !== 0) continue;
+      const mask = state.candidates(idx);
+      const count = popcount(mask);
+      if (best === null || count < best.count) best = { idx, mask, count };
+      if (count === 2) break;
+    }
+    return best;
+  }
+
+  function solve(state, stats, depth) {
+    stats.recursiveNodes += 1;
+    if (depth > stats.maxDepth) stats.maxDepth = depth;
+    const current = state.clone();
+    if (!propagateSingles(current, stats)) {
+      stats.backtracks += 1;
+      return null;
+    }
+    const best = selectUnfilledCell(current);
+    if (!best) return current;
+    for (const digit of maskToDigits(best.mask)) {
+      const next = current.clone();
+      const candidatesMask = next.candidates(best.idx);
+      next.moves.push({ index: best.idx, value: digit, candidatesMask, forced: false });
+      stats.guessedMoves += 1;
+      if (!next.place(best.idx, digit)) continue;
+      const solved = solve(next, stats, depth + 1);
+      if (solved) return solved;
+    }
+    stats.backtracks += 1;
+    return null;
+  }
+
+  function countSolutions(state, limit, countRef) {
+    if (countRef.count >= limit) return;
+    const current = state.clone();
+    const dummy = {
+      givens: 0,
+      blanks: 0,
+      forcedMoves: 0,
+      guessedMoves: 0,
+      recursiveNodes: 0,
+      backtracks: 0,
+      maxDepth: 0,
+    };
+    if (!propagateSingles(current, dummy)) return;
+    const best = selectUnfilledCell(current);
+    if (!best) {
+      countRef.count += 1;
+      return;
+    }
+    for (const digit of maskToDigits(best.mask)) {
+      if (countRef.count >= limit) return;
+      const next = current.clone();
+      if (next.place(best.idx, digit)) countSolutions(next, limit, countRef);
+    }
+  }
+
+  function computeReport(term) {
+    const raw = termToJsString(term);
+    if (raw === null) return null;
+    if (__sudokuReportCache.has(raw)) return __sudokuReportCache.get(raw);
+
+    const parsed = parsePuzzle(raw);
+    if (parsed.error) {
+      const rep = { status: 'invalid-input', error: parsed.error, raw, normalized: null };
+      __sudokuReportCache.set(raw, rep);
+      return rep;
+    }
+
+    const normalized = parsed.cells.join('');
+    const init = stateFromPuzzle(parsed.cells);
+    if (init.error) {
+      const rep = {
+        status: 'illegal-clues',
+        error: init.error,
+        raw,
+        normalized,
+        givens: parsed.cells.filter((v) => v !== 0).length,
+        blanks: parsed.cells.filter((v) => v === 0).length,
+        puzzleText: formatBoard(parsed.cells),
+      };
+      __sudokuReportCache.set(raw, rep);
+      return rep;
+    }
+
+    const initial = init.state;
+    const stats = {
+      givens: parsed.cells.filter((v) => v !== 0).length,
+      blanks: parsed.cells.filter((v) => v === 0).length,
+      forcedMoves: 0,
+      guessedMoves: 0,
+      recursiveNodes: 0,
+      backtracks: 0,
+      maxDepth: 0,
+    };
+
+    const solved = solve(initial, stats, 0);
+    if (!solved) {
+      const rep = {
+        status: 'unsatisfiable',
+        raw,
+        normalized,
+        givens: stats.givens,
+        blanks: stats.blanks,
+        recursiveNodes: stats.recursiveNodes,
+        backtracks: stats.backtracks,
+        puzzleText: formatBoard(parsed.cells),
+      };
+      __sudokuReportCache.set(raw, rep);
+      return rep;
+    }
+
+    const countRef = { count: 0 };
+    countSolutions(initial, 2, countRef);
+
+    const givensPreserved = parsed.cells.every((v, i) => v === 0 || v === solved.cells[i]);
+    const noBlanks = solved.cells.every((v) => v >= 1 && v <= 9);
+    const rowsComplete = Array.from({ length: 9 }, (_, r) =>
+      unitIsComplete(solved.cells.slice(r * 9, r * 9 + 9)),
+    ).every(Boolean);
+    const colsComplete = Array.from({ length: 9 }, (_, c) =>
+      unitIsComplete(Array.from({ length: 9 }, (_, r) => solved.cells[r * 9 + c])),
+    ).every(Boolean);
+    const boxesComplete = Array.from({ length: 9 }, (_, b) => {
+      const br = Math.floor(b / 3) * 3;
+      const bc = (b % 3) * 3;
+      const vals = [];
+      for (let dr = 0; dr < 3; dr += 1) {
+        for (let dc = 0; dc < 3; dc += 1) vals.push(solved.cells[(br + dr) * 9 + (bc + dc)]);
+      }
+      return unitIsComplete(vals);
+    }).every(Boolean);
+    const replayLegal = replayMovesAreLegal(parsed.cells, solved.moves);
+    const proofPathGuessCount = solved.moves.filter((m) => !m.forced).length;
+    const storyConsistent =
+      stats.recursiveNodes >= 1 &&
+      stats.maxDepth <= stats.blanks &&
+      solved.moves.length === stats.blanks &&
+      proofPathGuessCount <= stats.guessedMoves;
+
+    const rep = {
+      status: 'ok',
+      raw,
+      normalized,
+      givens: stats.givens,
+      blanks: stats.blanks,
+      forcedMoves: stats.forcedMoves,
+      guessedMoves: stats.guessedMoves,
+      recursiveNodes: stats.recursiveNodes,
+      backtracks: stats.backtracks,
+      maxDepth: stats.maxDepth,
+      unique: countRef.count === 1,
+      solution: solved.cells.join(''),
+      puzzleText: formatBoard(parsed.cells),
+      solutionText: formatBoard(solved.cells),
+      moveSummary: summarizeMoves(solved.moves, 8),
+      moveCount: solved.moves.length,
+      givensPreserved,
+      noBlanks,
+      rowsComplete,
+      colsComplete,
+      boxesComplete,
+      replayLegal,
+      storyConsistent,
+    };
+
+    __sudokuReportCache.set(raw, rep);
+    return rep;
+  }
+
+  function reportFieldAsTerm(report, field) {
+    if (!report) return null;
+    if (field === 'status') return makeStringLiteral(report.status);
+    if (field === 'error') return report.error ? makeStringLiteral(report.error) : null;
+    if (field === 'normalizedPuzzle') return report.normalized ? makeStringLiteral(report.normalized) : null;
+    if (field === 'solution') return report.solution ? makeStringLiteral(report.solution) : null;
+    if (field === 'puzzleText') return report.puzzleText ? makeStringLiteral(report.puzzleText) : null;
+    if (field === 'solutionText') return report.solutionText ? makeStringLiteral(report.solutionText) : null;
+    if (field === 'moveSummary') return report.moveSummary ? makeStringLiteral(report.moveSummary) : null;
+    if (field === 'givensPreservedText')
+      return report.givensPreserved === undefined ? null : makeStringLiteral(report.givensPreserved ? 'OK' : 'failed');
+    if (field === 'noBlanksText')
+      return report.noBlanks === undefined ? null : makeStringLiteral(report.noBlanks ? 'OK' : 'failed');
+    if (field === 'rowsCompleteText')
+      return report.rowsComplete === undefined ? null : makeStringLiteral(report.rowsComplete ? 'OK' : 'failed');
+    if (field === 'colsCompleteText')
+      return report.colsComplete === undefined ? null : makeStringLiteral(report.colsComplete ? 'OK' : 'failed');
+    if (field === 'boxesCompleteText')
+      return report.boxesComplete === undefined ? null : makeStringLiteral(report.boxesComplete ? 'OK' : 'failed');
+    if (field === 'replayLegalText')
+      return report.replayLegal === undefined ? null : makeStringLiteral(report.replayLegal ? 'OK' : 'failed');
+    if (field === 'storyConsistentText')
+      return report.storyConsistent === undefined ? null : makeStringLiteral(report.storyConsistent ? 'OK' : 'failed');
+
+    const boolFields = [
+      'unique',
+      'givensPreserved',
+      'noBlanks',
+      'rowsComplete',
+      'colsComplete',
+      'boxesComplete',
+      'replayLegal',
+      'storyConsistent',
+    ];
+    if (boolFields.includes(field))
+      return report[field] === undefined ? null : internLiteral(report[field] ? 'true' : 'false');
+
+    const numberFields = [
+      'givens',
+      'blanks',
+      'forcedMoves',
+      'guessedMoves',
+      'recursiveNodes',
+      'backtracks',
+      'maxDepth',
+      'moveCount',
+    ];
+    if (numberFields.includes(field)) return report[field] === undefined ? null : internLiteral(String(report[field]));
+
+    return null;
+  }
+
+  function evalSudokuField(goal, subst, field) {
+    const report = computeReport(goal.s);
+    if (!report) return [];
+    const term = reportFieldAsTerm(report, field);
+    if (!term) return [];
+    if (goal.o instanceof Var) {
+      const s2 = { ...subst };
+      s2[goal.o.name] = term;
+      return [s2];
+    }
+    const s2 = unifyTerm(goal.o, term, subst);
+    return s2 !== null ? [s2] : [];
+  }
+
+  const fields = [
+    'status',
+    'error',
+    'normalizedPuzzle',
+    'solution',
+    'givens',
+    'blanks',
+    'forcedMoves',
+    'guessedMoves',
+    'recursiveNodes',
+    'backtracks',
+    'maxDepth',
+    'unique',
+    'givensPreserved',
+    'noBlanks',
+    'rowsComplete',
+    'colsComplete',
+    'boxesComplete',
+    'replayLegal',
+    'storyConsistent',
+    'givensPreservedText',
+    'noBlanksText',
+    'rowsCompleteText',
+    'colsCompleteText',
+    'boxesCompleteText',
+    'replayLegalText',
+    'storyConsistentText',
+    'moveSummary',
+    'puzzleText',
+    'solutionText',
+    'moveCount',
+  ];
+
+  for (const field of fields) {
+    registerBuiltin(SUDOKU_NS + field, ({ goal, subst }) => evalSudokuField(goal, subst, field));
+  }
+};
+
+  };
   __modules["lib/builtins.js"] = function(require, module, exports){
 /**
  * Eyeling Reasoner — builtins
@@ -73,6 +541,152 @@ function __useNumericCacheKey(key) {
   return typeof key === 'string' && key.length <= MAX_NUMERIC_CACHE_KEY_LEN;
 }
 
+// ---------------------------------------------------------------------------
+// Custom builtin registry
+// ---------------------------------------------------------------------------
+const __customBuiltinHandlers = new Map(); // predicate IRI -> evaluator(ctx) => deltas[]
+const __loadedBuiltinModuleIds = new Set();
+
+function __validateBuiltinIri(iri) {
+  if (typeof iri !== 'string' || !iri) {
+    throw new TypeError('Custom builtin IRI must be a non-empty string');
+  }
+}
+
+function registerBuiltin(iri, handler) {
+  __validateBuiltinIri(iri);
+  if (typeof handler !== 'function') {
+    throw new TypeError(`Custom builtin ${iri} must be registered with a function handler`);
+  }
+  __customBuiltinHandlers.set(iri, handler);
+  return handler;
+}
+
+function unregisterBuiltin(iri) {
+  return __customBuiltinHandlers.delete(iri);
+}
+
+function listBuiltinIris() {
+  return Array.from(__customBuiltinHandlers.keys()).sort();
+}
+
+function __buildBuiltinRegistrationApi() {
+  return {
+    registerBuiltin,
+    unregisterBuiltin,
+    listBuiltinIris,
+    internIri,
+    internLiteral,
+    literalParts,
+    termToJsString,
+    termToJsStringDecoded,
+    termToN3,
+    iriValue,
+    unifyTerm,
+    applySubstTerm,
+    applySubstTriple,
+    proveGoals,
+    isGroundTerm,
+    computeConclusionFromFormula,
+    skolemIriFromGroundTerm,
+    parseBooleanLiteralInfo,
+    parseNumericLiteralInfo,
+    parseXsdDecimalToBigIntScale,
+    pow10n,
+    normalizeLiteralForFastKey,
+    literalsEquivalentAsXsdString,
+    materializeRdfLists,
+    terms: { Literal, Iri, Var, Blank, ListTerm, OpenListTerm, GraphTerm, Triple, Rule },
+    ns: { RDF_NS, XSD_NS, CRYPTO_NS, MATH_NS, TIME_NS, LIST_NS, LOG_NS, STRING_NS },
+  };
+}
+
+function registerBuiltinModule(mod, origin = '<builtin-module>') {
+  if (!mod) throw new TypeError(`Builtin module ${origin} did not export anything`);
+
+  const api = __buildBuiltinRegistrationApi();
+
+  if (typeof mod === 'function') {
+    mod(api);
+    return true;
+  }
+
+  if (typeof mod.register === 'function') {
+    mod.register(api);
+    return true;
+  }
+
+  const candidates = [];
+  if (mod && typeof mod.builtins === 'object' && mod.builtins) candidates.push(mod.builtins);
+  if (mod && typeof mod.default === 'object' && mod.default) candidates.push(mod.default);
+  candidates.push(mod);
+
+  let registeredAny = false;
+  for (const obj of candidates) {
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) continue;
+    for (const [iri, handler] of Object.entries(obj)) {
+      if (typeof handler !== 'function') continue;
+      registerBuiltin(iri, handler);
+      registeredAny = true;
+    }
+    if (registeredAny) return true;
+  }
+
+  throw new TypeError(
+    `Builtin module ${origin} must export a function, a { register() } object, or an object mapping predicate IRIs to handlers`,
+  );
+}
+
+function loadBuiltinModule(specifier, options = {}) {
+  if (typeof require !== 'function') {
+    throw new Error('Custom builtin modules can only be loaded when require() is available');
+  }
+  if (typeof specifier !== 'string' || !specifier) {
+    throw new TypeError('Builtin module specifier must be a non-empty string');
+  }
+
+  const path = require('node:path');
+  const resolved = options && options.resolveFrom ? path.resolve(options.resolveFrom, specifier) : specifier;
+  const moduleId = String(resolved);
+  if (__loadedBuiltinModuleIds.has(moduleId)) return moduleId;
+
+  const loaded = require(resolved);
+  registerBuiltinModule(loaded, moduleId);
+  __loadedBuiltinModuleIds.add(moduleId);
+  return moduleId;
+}
+
+function __evalRegisteredBuiltin(pv, goal, subst, facts, backRules, depth, varGen, maxResults) {
+  const handler = __customBuiltinHandlers.get(pv);
+  if (typeof handler !== 'function') return null;
+
+  const ctx = {
+    iri: pv,
+    goal,
+    subst,
+    facts,
+    backRules,
+    depth,
+    varGen,
+    maxResults,
+    api: __buildBuiltinRegistrationApi(),
+  };
+
+  try {
+    const out = handler(ctx);
+    if (out == null) return [];
+    if (!Array.isArray(out)) {
+      throw new TypeError(`Custom builtin ${pv} must return an array of substitution deltas`);
+    }
+    return out;
+  } catch (err) {
+    if (err && typeof err === 'object' && typeof err.message === 'string') {
+      err.message = `Error in custom builtin ${pv}: ${err.message}`;
+    }
+    throw err;
+  }
+}
+
 //
 // Engine hooks (injected once by makeBuiltins)
 //
@@ -1478,6 +2092,9 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
     if (pv !== allow1 && pv !== allow2) return [];
   }
 
+  const registeredBuiltinResult = __evalRegisteredBuiltin(pv, g, subst, facts, backRules, depth, varGen, maxResults);
+  if (registeredBuiltinResult !== null) return registeredBuiltinResult;
+
   // -----------------------------------------------------------------
   // 4.1 crypto: builtins
   // -----------------------------------------------------------------
@@ -3689,6 +4306,8 @@ function isBuiltinPred(p) {
     return true;
   }
 
+  if (__customBuiltinHandlers.has(v)) return true;
+
   return (
     v.startsWith(CRYPTO_NS) ||
     v.startsWith(MATH_NS) ||
@@ -3846,6 +4465,11 @@ function listHasTriple(list, tr) {
 
 module.exports = {
   makeBuiltins,
+  registerBuiltin,
+  unregisterBuiltin,
+  registerBuiltinModule,
+  loadBuiltinModule,
+  listBuiltinIris,
   // shared helpers used by engine/explain
   parseBooleanLiteralInfo,
   parseNumericLiteralInfo,
@@ -3922,7 +4546,7 @@ function main() {
       argv.push(a);
       continue;
     }
-    // Combined short flags (no flag in eyeling takes a value)
+    // Combined short flags (the long --builtin option takes a value)
     for (const ch of a.slice(1)) argv.push('-' + ch);
   }
   const prog = String(process.argv[1] || 'eyeling')
@@ -3934,6 +4558,7 @@ function main() {
       `Usage: ${prog} [options] <file.n3>\n\n` +
       `Options:\n` +
       `  -a, --ast                    Print parsed AST as JSON and exit.\n` +
+      `      --builtin <module.js>    Load a custom builtin module (repeatable).\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` +
@@ -3956,6 +4581,27 @@ function main() {
     process.exit(0);
   }
 
+  const builtinModules = [];
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--builtin') {
+      const next = argv[i + 1];
+      if (!next || next.startsWith('-')) {
+        console.error('Error: --builtin expects a module path.');
+        process.exit(1);
+      }
+      builtinModules.push(next);
+      i += 1;
+      continue;
+    }
+    if (typeof a === 'string' && a.startsWith('--builtin=')) {
+      builtinModules.push(a.slice('--builtin='.length));
+      continue;
+    }
+    if (!a.startsWith('-')) positional.push(a);
+  }
+
   const showAst = argv.includes('--ast') || argv.includes('-a');
   const streamMode = argv.includes('--stream') || argv.includes('-t');
 
@@ -3980,7 +4626,6 @@ function main() {
   }
 
   // Positional args (the N3 file)
-  const positional = argv.filter((a) => !a.startsWith('-'));
   if (positional.length === 0) {
     printHelp(false);
     process.exit(0);
@@ -3991,6 +4636,16 @@ function main() {
     process.exit(1);
   }
 
+  for (const spec of builtinModules) {
+    try {
+      if (typeof engine.loadBuiltinModule === 'function')
+        engine.loadBuiltinModule(spec, { resolveFrom: process.cwd() });
+    } catch (e) {
+      console.error(`Error loading builtin module ${JSON.stringify(spec)}: ${e && e.message ? e.message : String(e)}`);
+      process.exit(1);
+    }
+  }
+
   const filePath = positional[0];
   let text;
   try {
@@ -4754,6 +5409,11 @@ const { liftBlankRuleVars } = require('./rules');
 
 const {
   makeBuiltins,
+  registerBuiltin,
+  unregisterBuiltin,
+  registerBuiltinModule,
+  loadBuiltinModule,
+  listBuiltinIris,
   // helpers used by engine core
   parseBooleanLiteralInfo,
   parseNumericLiteralInfo,
@@ -5240,6 +5900,10 @@ const { evalBuiltin, isBuiltinPred } = makeBuiltins({
   termsEqualNoIntDecimal,
 });
 
+try {
+  registerBuiltinModule(require('./builtin-sudoku'), './builtin-sudoku');
+} catch (_) {}
+
 // Initialize proof/output helpers (implemented in lib/explain.js).
 const { printExplanation, collectOutputStringsFromFacts } = makeExplain({
   applySubstTerm,
@@ -7908,6 +8572,7 @@ function reasonStream(input, opts = {}) {
     enforceHttps = false,
     rdfjs = false,
     dataFactory = null,
+    builtinModules = null,
   } = opts;
 
   const parsedInput = normalizeParsedReasonerInputSync(input);
@@ -7917,6 +8582,12 @@ function reasonStream(input, opts = {}) {
   deref.setEnforceHttpsEnabled(!!enforceHttps);
   proofCommentsEnabled = !!proof;
 
+  if (Array.isArray(builtinModules)) {
+    for (const spec of builtinModules) loadBuiltinModule(spec);
+  } else if (typeof builtinModules === 'string' && builtinModules) {
+    loadBuiltinModule(builtinModules);
+  }
+
   let prefixes, triples, frules, brules, logQueryRules;
 
   if (parsedInput) {
@@ -8141,6 +8812,11 @@ module.exports = {
   setTracePrefixes,
   getDeterministicSkolemEnabled,
   setDeterministicSkolemEnabled,
+  registerBuiltin,
+  unregisterBuiltin,
+  registerBuiltinModule,
+  loadBuiltinModule,
+  listBuiltinIris,
 };
 
   };