eyeling 1.23.2 → 1.23.3

package/HANDBOOK.md

@@ -1891,9 +1891,17 @@ A few practical defaults are worth remembering:
 Custom builtins can be loaded explicitly from the CLI:
 
 ```bash
-npx eyeling --builtin lib/builtin-sudoku.js examples/sudoku.n3
+npx eyeling --builtin examples/builtin/sudoku.js examples/sudoku.n3
 ```
 
+Example-specific builtins live under `examples/builtin/`. When the examples test runner sees `examples/builtin/<stem>.js` next to `examples/<stem>.n3`, it auto-loads that builtin for the matching example by running the same command shape a user would run manually:
+
+```bash
+node eyeling.js --builtin examples/builtin/queens.js examples/queens.n3
+```
+
+Examples that do not need a custom builtin should not add a matching file under `examples/builtin/`. Examples that do need one should ship it there and let the examples test runner load it uniformly. For example, `examples/sudoku.n3` is paired with `examples/builtin/sudoku.js`, and `examples/queens.n3` is paired with `examples/builtin/queens.js`.
+
 ### 14.2 The bundled Node CLI/runtime (`eyeling.js`)
 
 The bundle contains the whole engine. The CLI path is the “canonical behavior”:
@@ -2376,14 +2384,16 @@ That API keeps the extension boundary explicit: custom builtins get the operatio
 
 ### 16.6 A shipped example: the Sudoku builtin
 
-The repository now ships a Sudoku builtin module (`lib/builtin-sudoku.js`) and a matching example program (`sudoku.n3`).
+The repository ships a Sudoku example program (`examples/sudoku.n3`) together with its example-specific builtin module (`examples/builtin/sudoku.js`).
 
-So this works out of the box:
+Run it explicitly like this:
 
 ```bash
-eyeling sudoku.n3
+eyeling --builtin examples/builtin/sudoku.js examples/sudoku.n3
 ```
 
+`npm run test:examples` uses the same convention automatically: when it sees `examples/builtin/sudoku.js` next to `examples/sudoku.n3`, it loads that module for the Sudoku example.
+
 That example is useful for two reasons:
 
 - it shows a realistic domain-specific builtin implemented outside the core builtin switchboard
@@ -2567,10 +2577,10 @@ It also supports **custom builtin modules**.
 - From JavaScript: `reason({ builtinModules: ['./my-builtins.js'] }, input)`
 - Programmatically in-process: `registerBuiltin(...)`, `registerBuiltinModule(...)`, `loadBuiltinModule(...)`
 
-A concrete shipped example is the Sudoku builtin and the root-level `sudoku.n3` program:
+A concrete shipped example is the Sudoku builtin paired with `examples/sudoku.n3`:
 
 ```bash
-eyeling sudoku.n3
+eyeling --builtin examples/builtin/sudoku.js examples/sudoku.n3
 ```
 
 References:

package/dist/browser/eyeling.browser.js

@@ -8,478 +8,6 @@
   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
@@ -6394,10 +5922,6 @@
       termsEqualNoIntDecimal,
     });
 
-    try {
-      registerBuiltinModule(require('./builtin-sudoku'), './builtin-sudoku');
-    } catch (_) {}
-
     // Initialize proof/output helpers (implemented in lib/explain.js).
     const { printExplanation, collectOutputStringsFromFacts } = makeExplain({
       applySubstTerm,

package/examples/builtin/queens.js

@@ -0,0 +1,141 @@
+'use strict';
+
+// Example-specific builtin module for examples/queens.n3.
+//
+// The N3 file keeps the example interface declarative:
+//   (16 0) queens:render ?Text
+//   (16 0) queens:count  ?Count
+//
+// This JavaScript module supplies the intentionally specialized hot loop. The
+// solver is the same 32-bit bit-mask kernel used in the standalone queens.js
+// benchmark: columns and diagonals are represented as integer masks, so a whole
+// row's legal moves are computed with a few bitwise operations.
+//
+// Why use a builtin instead of pure N3 rules?
+//   * A pure N3 generator for 16-Queens would create an enormous search tree.
+//   * The builtin keeps the example useful for performance demonstrations.
+//   * It also shows the intended pattern for expensive domain-specific kernels:
+//     put the tight computation in a custom builtin, then let N3 describe how
+//     the result is connected to the rest of the knowledge graph.
+//
+module.exports = ({ registerBuiltin, internLiteral, unifyTerm, applySubstTerm, parseNumericLiteralInfo, terms }) => {
+  const { ListTerm } = terms;
+  const NS = 'http://example.org/queens#';
+
+  // Cache by "N/MAX_PRINT" because the same N3 run may ask for both the count
+  // and the rendered report. Without this, queens:count and queens:render would
+  // solve the same board twice.
+  const resultCache = new Map();
+
+  function integerValue(term) {
+    const info = parseNumericLiteralInfo(term);
+    if (!info) return null;
+    if (info.kind === 'bigint') {
+      const n = Number(info.value);
+      return Number.isSafeInteger(n) ? n : null;
+    }
+    if (info.kind === 'number' && Number.isInteger(info.value)) return info.value;
+    return null;
+  }
+
+  function solveNQueens(n, maxPrint) {
+    if (!Number.isInteger(n) || n <= 0 || n > 31) {
+      throw new RangeError('queens:count expects 1 <= N <= 31');
+    }
+    if (!Number.isInteger(maxPrint) || maxPrint < 0) {
+      throw new RangeError('queens:count expects MAX_PRINT >= 0');
+    }
+
+    // JavaScript bitwise operators work on signed 32-bit integers. N <= 31 is
+    // therefore the safe range for this compact benchmark implementation.
+    const allColumns = Math.pow(2, n) - 1;
+    const board = new Array(n).fill(-1);
+    const printed = [];
+    let count = 0;
+
+    function boardText() {
+      const lines = [];
+      for (let row = 0; row < n; row++) {
+        const cells = [];
+        for (let col = 0; col < n; col++) cells.push(col === board[row] ? 'Q' : '.');
+        lines.push(cells.join(' '));
+      }
+      lines.push(`As column positions by row: [${board.map((col) => col + 1).join(', ')}]`);
+      return lines.join('\n');
+    }
+
+    function search(row, columns, diagLeft, diagRight) {
+      if (row === n) {
+        count++;
+        if (count <= maxPrint) printed.push(`Solution ${count}:\n${boardText()}`);
+        return;
+      }
+
+      // All legal columns for this row in one expression.
+      let available = allColumns & ~(columns | diagLeft | diagRight);
+      while (available !== 0) {
+        // Pick and clear the lowest set bit.
+        const position = available & -available;
+        available ^= position;
+
+        board[row] = Math.clz32(position) ^ 31;
+        search(row + 1, columns | position, (diagLeft | position) << 1, (diagRight | position) >> 1);
+        board[row] = -1;
+      }
+    }
+
+    search(0, 0, 0, 0);
+    return { count, printed };
+  }
+
+  registerBuiltin(NS + 'count', ({ goal, subst }) => {
+    const subject = applySubstTerm(goal.s, subst);
+    if (!(subject instanceof ListTerm) || subject.elems.length !== 2) return [];
+
+    const n = integerValue(applySubstTerm(subject.elems[0], subst));
+    const maxPrint = integerValue(applySubstTerm(subject.elems[1], subst));
+    if (n == null || maxPrint == null) return [];
+
+    const key = `${n}/${maxPrint}`;
+    let result = resultCache.get(key);
+    if (!result) {
+      result = solveNQueens(n, maxPrint);
+      resultCache.set(key, result);
+    }
+    const { count } = result;
+    const lit = internLiteral(String(count));
+    const next = unifyTerm(goal.o, lit, subst);
+    return next ? [next] : [];
+  });
+
+  registerBuiltin(NS + 'render', ({ goal, subst }) => {
+    const subject = applySubstTerm(goal.s, subst);
+    if (!(subject instanceof ListTerm) || subject.elems.length !== 2) return [];
+
+    const n = integerValue(applySubstTerm(subject.elems[0], subst));
+    const maxPrint = integerValue(applySubstTerm(subject.elems[1], subst));
+    if (n == null || maxPrint == null) return [];
+
+    const key = `${n}/${maxPrint}`;
+    let result = resultCache.get(key);
+    if (!result) {
+      result = solveNQueens(n, maxPrint);
+      resultCache.set(key, result);
+    }
+    const { count, printed } = result;
+    const body = [
+      `Solving ${n}-Queens...`,
+      `Printing at most ${maxPrint} solution(s).`,
+      '',
+      ...printed,
+      ...(printed.length ? [''] : []),
+      `Total solutions for ${n}-Queens: ${count}`,
+      '',
+    ].join('\n');
+
+    // Eyeling string literals are represented by their quoted lexical form.
+    const lit = internLiteral(JSON.stringify(body));
+    const next = unifyTerm(goal.o, lit, subst);
+    return next ? [next] : [];
+  });
+};

package/{lib/builtin-sudoku.js → examples/builtin/sudoku.js}

@@ -1,5 +1,20 @@
 'use strict';
 
+// Example-specific builtin module for examples/sudoku.n3.
+//
+// The N3 file keeps the Sudoku report declarative: it asks predicates in the
+// http://example.org/sudoku-builtin# namespace for facts such as the normalized
+// puzzle, solution, move counts, and validation checks.
+//
+// This JavaScript module supplies the specialized Sudoku search/verification
+// kernel. It is loaded by the examples test runner in the same uniform way as
+// examples/builtin/queens.js:
+//
+//   node eyeling.js --builtin examples/builtin/sudoku.js examples/sudoku.n3
+//
+// Keeping this under examples/builtin/ makes the example self-contained and
+// avoids registering example-specific predicates in the core runtime.
+
 module.exports = function registerSudokuBuiltins(api) {
   const { registerBuiltin, internLiteral, termToJsString, unifyTerm, terms } = api;
   const { Var } = terms;

package/examples/output/queens.txt

@@ -0,0 +1,21 @@
+Solving 14-Queens...
+Printing at most 1 solution(s).
+
+Solution 1:
+Q . . . . . . . . . . . . .
+. . Q . . . . . . . . . . .
+. . . . Q . . . . . . . . .
+. . . . . . Q . . . . . . .
+. . . . . . . . . . . Q . .
+. . . . . . . . . Q . . . .
+. . . . . . . . . . . . Q .
+. . . Q . . . . . . . . . .
+. . . . . . . . . . . . . Q
+. . . . . . . . Q . . . . .
+. Q . . . . . . . . . . . .
+. . . . . Q . . . . . . . .
+. . . . . . . Q . . . . . .
+. . . . . . . . . . Q . . .
+As column positions by row: [1, 3, 5, 7, 12, 10, 13, 4, 14, 9, 2, 6, 8, 11]
+
+Total solutions for 14-Queens: 365596

package/examples/queens.n3

@@ -0,0 +1,20 @@
+# N-Queens benchmark wrapper for Eyeling.
+#
+# Run:
+#   node eyeling.js --builtin examples/builtin/queens.js examples/queens.n3
+#
+# The tight bit-mask search kernel lives in examples/builtin/queens.js.
+# Pure N3 can express N-Queens declaratively, but a 16x16 exhaustive count is
+# not a practical pure-N3 benchmark for the current engine.
+
+@prefix : <http://example.org/queens#>.
+@prefix log: <http://www.w3.org/2000/10/swap/log#>.
+
+:run :n 14; :maxPrint 1.
+
+{
+  :run :n ?N; :maxPrint ?MaxPrint.
+  (?N ?MaxPrint) :render ?Report.
+} log:query {
+  :answer log:outputString ?Report.
+}.

package/examples/sudoku.n3

@@ -1,7 +1,13 @@
 # ==================================================
 # sudoku.n3
 #
-# A standalone Sudoku solver and report generator.
+# A Sudoku solver and report generator.
+#
+# Run:
+#   node eyeling.js --builtin examples/builtin/sudoku.js examples/sudoku.n3
+#
+# The specialized solver lives in examples/builtin/sudoku.js. The N3 below
+# describes the report and validation checks around that solver.
 #
 # Edit :case :puzzle to solve another puzzle.
 # Accepted blanks: 0, ., _

package/eyeling.js

@@ -8,474 +8,6 @@
   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
@@ -6373,10 +5905,6 @@ 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,
@@ -10770,7 +10298,7 @@ function parseN3SourceList(input, opts = {}) {
   if (!isN3SourceListInput(input)) return null;
   const sources = input.sources.map(normalizeN3SourceItem);
   const defaultBaseIri = typeof opts.baseIri === 'string' ? opts.baseIri : '';
-  const parsed = sources.map(source =>
+  const parsed = sources.map((source) =>
     parseN3Text(source.text, {
       label: source.label,
       baseIri: source.baseIri || (sources.length === 1 ? defaultBaseIri : ''),

package/lib/engine.js

@@ -610,10 +610,6 @@ 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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.23.2",
+  "version": "1.23.3",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [

package/test/examples.test.js

@@ -96,6 +96,14 @@ function resolveExpectedPath(outputDir, inputFile) {
   return path.join(outputDir, candidates[0]);
 }
 
+function resolveExampleBuiltinPath(root, inputFile) {
+  const stem = path.basename(inputFile, path.extname(inputFile));
+  const rel = path.join('examples', 'builtin', `${stem}.js`);
+  const abs = path.join(root, rel);
+  if (!fs.existsSync(abs)) return null;
+  return { abs, rel };
+}
+
 function main() {
   const suiteStart = Date.now();
 
@@ -170,17 +178,32 @@ function main() {
     const tmpDir = mkTmpDir();
     const generatedPath = path.join(tmpDir, 'generated.n3');
 
-    // Run eyeling on this file (cwd examplesDir so relative behavior matches old script)
+    // Run eyeling on this file. If examples/builtin/<stem>.js exists,
+    // load it for the matching examples/<stem>.n3 file. Builtin-backed examples
+    // run from the repository root so the command shape matches documented usage:
+    //   node eyeling.js --builtin examples/builtin/foo.js examples/foo.n3
+    const builtin = resolveExampleBuiltinPath(root, file);
     const outFd = fs.openSync(generatedPath, 'w');
-
-    const r = cp.spawnSync(nodePath, [eyelingJsPath, '-d', file], {
-      cwd: examplesDir,
-      stdio: ['ignore', outFd, 'pipe'], // stdout -> file, stderr captured
-      maxBuffer: 200 * 1024 * 1024,
-      encoding: 'utf8',
-    });
-
-    fs.closeSync(outFd);
+    let r;
+    try {
+      if (builtin) {
+        r = cp.spawnSync(nodePath, [eyelingJsPath, '-d', '--builtin', builtin.rel, path.join('examples', file)], {
+          cwd: root,
+          stdio: ['ignore', outFd, 'pipe'], // stdout -> file, stderr captured
+          maxBuffer: 200 * 1024 * 1024,
+          encoding: 'utf8',
+        });
+      } else {
+        r = cp.spawnSync(nodePath, [eyelingJsPath, '-d', file], {
+          cwd: examplesDir,
+          stdio: ['ignore', outFd, 'pipe'], // stdout -> file, stderr captured
+          maxBuffer: 200 * 1024 * 1024,
+          encoding: 'utf8',
+        });
+      }
+    } finally {
+      fs.closeSync(outFd);
+    }
 
     const rc = r.status == null ? 1 : r.status;