eyeling 1.33.4 → 1.33.5

package/README.md

@@ -1153,6 +1153,7 @@ Everything else should be treated as internal unless explicitly documented.
 ├── bin/                      CLI executable shim
 ├── lib/                      Source modules
 ├── dist/browser/             Browser bundle and ESM wrapper
+├── docs/                     Project documentation, including the eyelang language reference
 ├── examples/                 N3 examples, RDF message inputs, and generated decks
 ├── spec/                     RDF 1.2 parser test adapter
 ├── test/                     API, built-in, store, example, package, playground, and stream tests

package/{examples/eyelang/SPEC.md → docs/eyelang-language-reference.md}

@@ -1,4 +1,4 @@
-# eyelang Language Specification
+# eyelang Language Reference
 
 ## Table of contents
 
@@ -77,7 +77,7 @@ A **term** is a variable, atom constant, string, number, list, or compound term.
 
 An **atom constant** is a symbolic scalar term, such as `pat`, `type`, or `'atom with spaces'`. It is a term and may appear as an argument, list element, functor name, or predicate name.
 
-An **atomic formula** is a predicate application such as `parent(pat, jan)` or `status(case1, accepted)`. It is the unit of truth in a Herbrand interpretation. In some logic-programming literature atomic formulas are called "atoms"; this specification avoids that shorthand. Whenever the noun "atom" appears here outside a built-in name such as `formula_atom/2`, it means **atom constant**, not atomic formula.
+An **atomic formula** is a predicate application such as `parent(pat, jan)` or `status(case1, accepted)`. It is the unit of truth in a Herbrand interpretation. In some logic-programming literature atomic formulas are called "atoms"; this specification avoids that shorthand. Whenever the noun "atom" appears here outside the phrase "atomic formula", it means **atom constant**.
 
 This distinction is normative: `pat` is an atom constant and can appear as a term argument; `parent(pat, jan)` is an atomic formula and can appear as a fact, rule head, or goal. A compound term such as `pair(pat, jan)` has the same surface shape as an atomic formula, but its role is determined by context: as data it is a compound term, and as a clause head or goal it is an atomic formula with predicate symbol `pair/2`.
 
@@ -252,7 +252,7 @@ Parenthesized comma terms may be goals or data:
 (name(alice, "Alice"), knows(alice, bob))
 ```
 
-When a comma term appears as a goal, it is evaluated as conjunction. When it appears as data, it remains a term. `formula_atom/2` and `formula_binary/4` enumerate members inside such formula terms.
+When a comma term appears as a goal, it is evaluated as conjunction. When it appears as data, it remains a term. `formula_binary/4` enumerates binary members inside such formula terms.
 
 ## 6. Clauses and predicates
 
@@ -368,7 +368,7 @@ Implementations MAY provide additional built-ins, but such built-ins are extensi
 | `div(A, B, C)` | `C = A / B`; integer inputs use integer division. |
 | `mod(A, B, C)` | Integer remainder. |
 | `pow(A, B, C)` | `C = A^B`. |
-| `max(A, B, C)`, `min(A, B, C)` | Numeric maximum or minimum. |
+| `min(A, B, C)` | Numeric minimum. |
 
 ### 9.3 Comparison
 
@@ -399,10 +399,8 @@ Comparisons interpret numeric-looking terms numerically. Other scalar terms are
 
 | Built-in | Meaning |
 |---|---|
-| `atom_concat(A, B, C)` | Atom-constant concatenation. |
 | `str_concat(A, B, C)` | String concatenation. |
 | `contains(Text, Needle)` | Text contains `Needle`. |
-| `not_contains(Text, Needle)` | Text does not contain `Needle`. |
 | `matches(Text, Pattern)` | Text matches a simple implementation regex/search pattern. |
 | `not_matches(Text, Pattern)` | Negation of `matches/2`. |
 
@@ -419,7 +417,6 @@ Comparisons interpret numeric-looking terms numerically. Other scalar terms are
 | `not_member(X, List)` | Succeeds when `X` is not a member. |
 | `reverse(A, B)` | Reverses a proper list. |
 | `length(List, N)` | Proper-list length. |
-| `is_list(X)` | Succeeds when `X` is a proper list. |
 
 ### 9.8 Aggregation and ordering
 
@@ -434,11 +431,10 @@ Comparisons interpret numeric-looking terms numerically. Other scalar terms are
 
 ### 9.9 Formula terms
 
-Formula terms are data representations of atomic formulas and comma conjunctions. `formula_atom/2` uses "atom" in the logic-programming sense of atomic formula; it MUST NOT be confused with atom constants such as `alice` or `name`.
+Formula terms are data representations of atomic formulas and comma conjunctions.
 
 | Built-in | Meaning |
 |---|---|
-| `formula_atom(Formula, Atom)` | Enumerates atomic-formula members inside comma formula data. The second argument denotes an atomic formula term, not necessarily an atom constant. |
 | `formula_binary(Formula, S, P, O)` | Enumerates binary formula members `P(S, O)`, exposing the functor as atom constant `P`. |
 
 Example:
@@ -470,7 +466,7 @@ An extension built-in SHOULD obey the same surface-language discipline as standa
 - it SHOULD document its intended modes, especially which arguments must be ground before it runs deterministically;
 - it MUST NOT change the meaning of ordinary facts, rules, unification, or standard built-ins.
 
-For example, an implementation may include extension modules for Sudoku solving, portfolio selection, number-theory algorithms, graph search, matrix operations, or alphametic puzzles. Those modules may be valuable and may make example programs much faster, but their predicate names, arities, algorithms, and modes are implementation-defined unless they are separately standardized.
+For example, an implementation may include extension modules for portfolio selection, number-theory algorithms, graph search, matrix operations, or alphametic puzzles. Those modules may be valuable and may make example programs much faster, but their predicate names, arities, algorithms, and modes are implementation-defined unless they are separately standardized.
 
 An implementation that provides explanation output SHOULD make extension built-ins explainable at least as opaque successful or failed built-in calls, so that proof traces do not incorrectly report "no clauses" for a host-provided relation.
 

package/examples/eyelang/README.md

@@ -10,7 +10,7 @@ Programs write relations directly, for example `ancestor(pat, emma)` or `status(
 
 Try it in the [browser playground](https://eyereasoner.github.io/eyelang/playground). The playground includes run options equivalent to CLI `--stats` and `--proof`.
 
-For the normative language definition, including lexical syntax, terms, clauses, goals, built-ins, `memoize/2`, `materialize/2`, and conformance boundaries, read the [eyelang specification](SPEC.md).
+For the normative language definition, including lexical syntax, terms, clauses, goals, built-ins, `memoize/2`, `materialize/2`, and conformance boundaries, read the [eyelang language reference](../../docs/eyelang-language-reference.md).
 
 ## Contents
 
@@ -243,7 +243,7 @@ The CLI is output-oriented and uses `materialize/2` to decide what to print. Emb
 Add `-s` or `--stats` when you want lightweight solver counters on stderr without changing stdout:
 
 ```sh
-bin/eyelang -s examples/sudoku.pl
+bin/eyelang -s examples/eyelang/n-queens.pl
 ```
 
 The playground has matching `--stats` and `--proof` checkboxes, so browser runs can show the same counters or explanations like the CLI.
@@ -251,15 +251,11 @@ The playground has matching `--stats` and `--proof` checkboxes, so browser runs
 
 ### Builtins
 
-eyelang builtins are registered by name and arity in small modules under [`src/builtins`](src/builtins). This keeps the runtime portable to Node.js and the browser while giving each builtin family a clear boundary. Builtins are enabled by normal predicate calls.
+eyelang builtins are registered by name and arity in small modules under [`lib/eyelang/builtins`](../../lib/eyelang/builtins). This keeps the runtime portable to Node.js and the browser while giving each builtin family a clear boundary. Builtins are enabled by normal predicate calls.
 
-The core builtin families cover unification, arithmetic, comparison, dates, strings, lists, aggregation, formula terms, and search control. Additional reusable finite-search helpers are available for examples that would otherwise need large amounts of repetitive generate-and-test code. These helpers are deliberately general relations rather than shortcuts tied to a particular example name. For example:
+The core builtin families cover unification, arithmetic, comparison, dates, strings, lists, aggregation, formula terms, and search control. Additional reusable finite-search helpers are available only where bundled examples need them to avoid large amounts of repetitive generate-and-test code. These helpers are deliberately general relations rather than shortcuts tied to a particular example name. For example:
 
 ```prolog
-solution(Name, Rows) :-
-  puzzle(Name, Grid),
-  sudoku(Grid, Rows).
-
 answer(Queens) :-
   n_queens(8, Queens).
 
@@ -268,11 +264,9 @@ best(Cycle, Cost) :-
   weighted_hamiltonian_cycle(edge, Cities, Cycle, Cost).
 ```
 
-`sudoku/2` accepts either an 81-character string or a 9x9 list. Digits `1` to `9` are givens; `0`, `.`, and `_` mark blanks. It returns the solved 9x9 list.
-
-The reusable search and numeric helpers include `atom_range/4`, `atom_ranges/4`, `n_queens/2`, Hamiltonian path/cycle helpers, `cnf_model/3`, Quine-McCluskey helpers, bounded subset/path helpers, number-theory helpers such as `extended_gcd/5`, matrix helpers such as `matrix_multiply/2`, and `alphametic_sum/5`. These helpers are extension builtins of this implementation; [`SPEC.md`](SPEC.md) defines the portable core and standard builtin profile.
+The reusable search and numeric helpers include `n_queens/2`, Hamiltonian path/cycle helpers, `cnf_model/3`, Quine-McCluskey helpers, bounded subset/path helpers, number-theory helpers such as `extended_gcd/5`, matrix helpers such as `matrix_multiply/2`, and `alphametic_sum/5`. These helpers are extension builtins of this implementation; [the eyelang language reference](../../docs/eyelang-language-reference.md) defines the portable core and standard builtin profile.
 
-To add a builtin, create or extend a module with `register(registry)` and call `registry.add(name, arity, handler, options)`. The default registry is assembled in [`src/builtins/registry.js`](src/builtins/registry.js). Builtins that are only safe for specific argument modes should provide a `ready` predicate and `fallbackWhenNotReady: true`, so user-defined clauses remain visible until the builtin is applicable.
+To add a builtin, create or extend a module with `register(registry)` and call `registry.add(name, arity, handler, options)`. The default registry is assembled in [`lib/eyelang/builtins/registry.js`](../../lib/eyelang/builtins/registry.js). Builtins that are only safe for specific argument modes should provide a `ready` predicate and `fallbackWhenNotReady: true`, so user-defined clauses remain visible until the builtin is applicable.
 
 
 ## Aggregation helpers
@@ -298,13 +292,7 @@ best_cycle(Cycle, Cost) :-
 
 ## Formula data
 
-Comma terms can be data as well as conjunctions. eyelang provides relation-oriented formula utilities.
-
-`formula_atom(Formula, Atom)` enumerates atomic formula terms inside a comma formula:
-
-```prolog
-formula_atom((name(alice, "Alice"), knows(alice, bob)), X).
-```
+Comma terms can be data as well as conjunctions. eyelang provides a relation-oriented formula utility.
 
 `formula_binary(Formula, S, P, O)` enumerates binary terms and exposes their functor as an atom constant:
 
@@ -380,7 +368,6 @@ The repository includes examples for recursion, graph reachability, finite searc
 | [`equivalence-classes-overlap-implies-same-class.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/equivalence-classes-overlap-implies-same-class.pl) | Packages the shared-member proof pattern for equivalence classes. | [`output/equivalence-classes-overlap-implies-same-class.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/equivalence-classes-overlap-implies-same-class.pl) |
 | [`eulerian-path.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/eulerian-path.pl) | Finds an Eulerian path using each edge once. | [`output/eulerian-path.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/eulerian-path.pl) |
 | [`ev-range-worlds.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/ev-range-worlds.pl) | Estimates electric-vehicle trip feasibility. | [`output/ev-range-worlds.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/ev-range-worlds.pl) |
-| [`exact-cover-sudoku.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/exact-cover-sudoku.pl) | Solves Sudoku via exact-cover-style constraints. | [`output/exact-cover-sudoku.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/exact-cover-sudoku.pl) |
 | [`existential-rule.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/existential-rule.pl) | Represents existential witnesses with explicit Skolem-style terms. | [`output/existential-rule.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/existential-rule.pl) |
 | [`exoplanet-validation-worlds.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/exoplanet-validation-worlds.pl) | Validates exoplanet candidates across worlds. | [`output/exoplanet-validation-worlds.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/exoplanet-validation-worlds.pl) |
 | [`expression-eval.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/expression-eval.pl) | Evaluates a small arithmetic expression tree. | [`output/expression-eval.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/expression-eval.pl) |
@@ -448,7 +435,6 @@ The repository includes examples for recursion, graph reachability, finite searc
 | [`socket-family.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/socket-family.pl) | Shows socket-declared family-source inputs and ancestry rules. | [`output/socket-family.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/socket-family.pl) |
 | [`socrates.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/socrates.pl) | Derives that Socrates is mortal. | [`output/socrates.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/socrates.pl) |
 | [`statistics-summary.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/statistics-summary.pl) | Computes population statistics for a sample. | [`output/statistics-summary.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/statistics-summary.pl) |
-| [`sudoku.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/sudoku.pl) | Solves generic 9x9 Sudoku strings through the sudoku/2 builtin. | [`output/sudoku.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/sudoku.pl) |
 | [`superdense-coding.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/superdense-coding.pl) | Models superdense-coding bit transmission. | [`output/superdense-coding.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/superdense-coding.pl) |
 | [`traveling-salesman.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/traveling-salesman.pl) | Finds an optimal traveling-salesman tour. | [`output/traveling-salesman.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/traveling-salesman.pl) |
 | [`turing.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/turing.pl) | Simulates a binary-increment Turing machine. | [`output/turing.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/turing.pl) |
@@ -483,7 +469,7 @@ Run the full test suite:
 npm test
 ```
 
-The test suite runs in this order: Conformance, Regression/API/White-box, Examples. Each section prints its own subtotal, followed by a suite-specific grand total. The suite checks the conformance cases derived from `SPEC.md`, supplemental regression/API/white-box checks, and every runnable example against its golden output.
+The test suite runs in this order: Conformance, Regression/API/White-box, Examples. Each section prints its own subtotal, followed by a suite-specific grand total. The suite checks the conformance cases derived from the language reference, supplemental regression/API/white-box checks, and every runnable example against its golden output.
 
 Run only one suite when you are iterating:
 
@@ -493,7 +479,7 @@ npm run test:regression
 npm run test:examples
 ```
 
-The conformance suite lives in [`conformance/`](conformance/) and is split into `core` and `extension` profiles matching `SPEC.md`. Each case is a small program with an exact expected stdout file, and some internal conformance cases also include a goal file for testing the embeddable solver, so other implementations can reuse the same cases. The regression suite lives in [`test/run-regression.js`](test/run-regression.js) and covers CLI regressions, the public JavaScript API, and white-box invariants for parser, unification, and indexing behavior.
+The conformance suite lives in [`conformance/`](conformance/) and is split into `core` and `extension` profiles matching the language reference. Each case is a small program with an exact expected stdout file, and some internal conformance cases also include a goal file for testing the embeddable solver, so other implementations can reuse the same cases. The regression suite lives in [`test/run-regression.js`](test/run-regression.js) and covers CLI regressions, the public JavaScript API, and white-box invariants for parser, unification, and indexing behavior.
 
 ## Development and release
 
@@ -510,13 +496,13 @@ node bin/eyelang --help
 Useful profiling smoke test:
 
 ```sh
-bin/eyelang -s examples/sudoku.pl > /dev/null
+bin/eyelang -s examples/eyelang/n-queens.pl > /dev/null
 ```
 
 For a release:
 
 1. update `VERSION`;
-2. update `README.md` and `SPEC.md`;
+2. update `README.md` and the language reference;
 3. regenerate golden outputs if behavior changed;
 4. run `npm test`;
 5. publish the repository with `playground.html` and `playground-worker.mjs` if publishing the playground. The playground includes controls equivalent to CLI `--stats` and `--proof`.

package/lib/eyelang/builtins/arithmetic.js

@@ -3,7 +3,7 @@
 import { compareIntegerText, deref, isDecimalInteger, lexicalValue, numberTerm, numberTextFromDouble, parseFiniteNumber, unify } from '../term.js';
 
 const unaryNames = ['neg', 'abs', 'sin', 'cos', 'asin', 'acos', 'rounded', 'log'];
-const binaryNames = ['add', 'sub', 'mul', 'div', 'mod', 'max', 'min', 'pow'];
+const binaryNames = ['add', 'sub', 'mul', 'div', 'mod', 'min', 'pow'];
 const compareNames = ['lt', 'gt', 'le', 'ge'];
 
 export const arithmeticBuiltins = {
@@ -60,7 +60,6 @@ function binary(name) {
       else if (name === 'sub') out = (a - b).toString();
       else if (name === 'mul') out = (a * b).toString();
       else if (name === 'div') { if (b === 0n) return; out = (a / b).toString(); }
-      else if (name === 'max') out = (a >= b ? a : b).toString();
       else if (name === 'min') out = (a <= b ? a : b).toString();
       else if (name === 'pow') { if (b < 0n) return; out = (a ** b).toString(); }
     } else if (name === 'mod') {
@@ -77,7 +76,6 @@ function binary(name) {
       else if (name === 'mul') value = a * b;
       else if (name === 'div') { if (b === 0) return; value = a / b; }
       else if (name === 'pow') value = Math.pow(a, b);
-      else if (name === 'max') value = Math.max(a, b);
       else if (name === 'min') value = Math.min(a, b);
       out = numberTextFromDouble(value);
     }

package/lib/eyelang/builtins/formula.js

@@ -4,26 +4,10 @@ import { atom, deref, isConjunction, unify } from '../term.js';
 
 export const formulaBuiltins = {
   register(registry) {
-    registry.add('formula_atom', 2, formulaAtom);
     registry.add('formula_binary', 4, formulaBinary);
   }
 };
 
-function* emitFormulaAtoms(formula, target, env) {
-  formula = deref(formula, env);
-  if (isConjunction(formula)) {
-    yield* emitFormulaAtoms(formula.args[0], target, env);
-    yield* emitFormulaAtoms(formula.args[1], target, env);
-    return;
-  }
-  if (formula.type !== 'compound') return;
-  const next = env.clone();
-  if (unify(target, formula, next)) yield next;
-}
-
-function* formulaAtom({ goal, env }) {
-  yield* emitFormulaAtoms(goal.args[0], goal.args[1], env);
-}
 
 function* emitFormulaBinary(formula, subject, predicate, object, env) {
   formula = deref(formula, env);

package/lib/eyelang/builtins/lists.js

@@ -13,7 +13,6 @@ export const listBuiltins = {
     registry.add('not_member', 2, notMember, { deterministic: true });
     registry.add('reverse', 2, reverse, { deterministic: true });
     registry.add('length', 2, lengthBuiltin, { deterministic: true });
-    registry.add('is_list', 1, isList, { deterministic: true });
     registry.add('sort', 2, sortBuiltin, { deterministic: true });
   }
 };
@@ -133,10 +132,6 @@ function* lengthBuiltin({ goal, env }) {
   if (unify(goal.args[1], numberTerm(items.length), next)) yield next;
 }
 
-function* isList({ goal, env }) {
-  const items = properListItems(goal.args[0], env);
-  if (items) yield env;
-}
 
 function* sortBuiltin({ goal, env }) {
   const items = properListItems(goal.args[0], env);

package/lib/eyelang/builtins/registry.js

@@ -7,7 +7,6 @@ import { listBuiltins } from './lists.js';
 import { aggregationBuiltins } from './aggregation.js';
 import { formulaBuiltins } from './formula.js';
 import { controlBuiltins } from './control.js';
-import { sudokuBuiltins } from './sudoku.js';
 import { portfolioBuiltins } from './portfolio.js';
 import { searchBuiltins } from './search.js';
 import { numberTheoryBuiltins } from './number-theory.js';
@@ -39,7 +38,7 @@ export class BuiltinRegistry {
 
 export function createDefaultRegistry() {
   const registry = new BuiltinRegistry();
-  for (const mod of [coreBuiltins, arithmeticBuiltins, stringBuiltins, listBuiltins, aggregationBuiltins, formulaBuiltins, controlBuiltins, sudokuBuiltins, portfolioBuiltins, searchBuiltins, numberTheoryBuiltins, matrixBuiltins, alphameticBuiltins]) {
+  for (const mod of [coreBuiltins, arithmeticBuiltins, stringBuiltins, listBuiltins, aggregationBuiltins, formulaBuiltins, controlBuiltins, portfolioBuiltins, searchBuiltins, numberTheoryBuiltins, matrixBuiltins, alphameticBuiltins]) {
     mod.register(registry);
   }
   return registry;

package/lib/eyelang/builtins/search.js

@@ -1,14 +1,12 @@
 // Reusable finite-search builtins for examples that would otherwise spend most
 // of their time in small relational generators.  These predicates are generic
-// entry points (graph, CNF, QMC, range, and n-queens helpers), not compiled
+// entry points (graph, CNF, QMC, and n-queens helpers), not compiled
 // replacements for particular example predicate names.
 import { atom, compound, deref, listFromItems, numberTerm, properListItems, unify } from '../term.js';
 import { compareLexicalOrNumeric } from './arithmetic.js';
 
 export const searchBuiltins = {
   register(registry) {
-    registry.add('atom_range', 4, atomRange, { fallbackWhenNotReady: true, ready: atomRangeReady });
-    registry.add('atom_ranges', 4, atomRanges, { fallbackWhenNotReady: true, ready: atomRangesReady });
     registry.add('n_queens', 2, nQueens, { fallbackWhenNotReady: true, ready: firstIntReady });
     registry.add('weighted_hamiltonian_cycle', 4, weightedHamiltonianCycle, { fallbackWhenNotReady: true, ready: weightedGraphReady });
     registry.add('weighted_hamiltonian_path', 4, weightedHamiltonianPath, { fallbackWhenNotReady: true, ready: weightedGraphReady });
@@ -26,67 +24,9 @@ function graphReady(goal, env) { return atomKey(deref(goal.args[0], env)) !== nu
 function weightedGraphReady(goal, env) { return graphReady(goal, env); }
 function fixedCycleReady(goal, env) { return atomKey(deref(goal.args[0], env)) !== null && intTerm(goal.args[1], env) !== null; }
 function boundedPathReady(goal, env) { return atomKey(deref(goal.args[0], env)) !== null && atomKey(deref(goal.args[1], env)) !== null && atomKey(deref(goal.args[2], env)) !== null && intTerm(goal.args[3], env) !== null; }
-function atomRangeReady(goal, env) { return atomKey(deref(goal.args[0], env)) !== null && intTerm(goal.args[1], env) !== null && intTerm(goal.args[2], env) !== null; }
-function atomRangesReady(goal, env) { return atomList(goal.args[0], env) !== null && intTerm(goal.args[1], env) !== null && intTerm(goal.args[2], env) !== null; }
 function cnfReady(goal, env) { return atomList(goal.args[0], env) !== null && clauseList(goal.args[1], env) !== null; }
 function qmReady(goal, env) { return numberList(goal.args[0], env) !== null && numberList(goal.args[1], env) !== null && bitTable(goal.args[2], env) !== null; }
 
-function* atomRange({ goal, env }) {
-  // atom_range(Prefix, Low, High, Atom) is a compact generator for atoms such
-  // as n1, n2, ...; it replaces between/3 + atom_concat/3 in large generated
-  // data sets without committing to any domain-specific predicate name.
-  const prefix = atomKey(deref(goal.args[0], env));
-  const low = intTerm(goal.args[1], env);
-  const high = intTerm(goal.args[2], env);
-  if (prefix == null || low == null || high == null) return;
-  const output = deref(goal.args[3], env);
-  if (output.type !== 'var') {
-    const text = atomKey(output);
-    const n = parsePrefixedInteger(prefix, text);
-    if (n == null || n < low || n > high) return;
-    yield env;
-    return;
-  }
-  for (let i = low; i <= high; i++) {
-    const next = env.clone();
-    next.bind(output.name, atom(`${prefix}${i}`));
-    yield next;
-  }
-}
-
-function parsePrefixedInteger(prefix, text) {
-  if (text == null || !text.startsWith(prefix)) return null;
-  const suffix = text.slice(prefix.length);
-  if (!/^\d+$/.test(suffix)) return null;
-  const n = Number(suffix);
-  return Number.isSafeInteger(n) ? n : null;
-}
-
-function* atomRanges({ goal, env }) {
-  // atom_ranges([p, q], Low, High, Atom) is the multi-prefix companion to
-  // atom_range/4. It is useful when several generated atom families feed the
-  // same relation.
-  const prefixes = atomList(goal.args[0], env);
-  const low = intTerm(goal.args[1], env);
-  const high = intTerm(goal.args[2], env);
-  if (!prefixes || low == null || high == null) return;
-  const output = deref(goal.args[3], env);
-  if (output.type !== 'var') {
-    const text = atomKey(output);
-    for (const prefix of prefixes) {
-      const n = parsePrefixedInteger(prefix, text);
-      if (n != null && n >= low && n <= high) { yield env; return; }
-    }
-    return;
-  }
-  for (const prefix of prefixes) {
-    for (let i = low; i <= high; i++) {
-      const next = env.clone();
-      next.bind(output.name, atom(`${prefix}${i}`));
-      yield next;
-    }
-  }
-}
 
 function* nQueens({ goal, env }) {
   // n_queens(N, Solution) performs the same finite search as the declarative

package/lib/eyelang/builtins/strings.js

@@ -1,24 +1,21 @@
-// String and atom conversion builtins.
+// String builtins.
 // They mostly project from already-ground terms to avoid guessing string domains.
-import { atom, lexicalValue, stringTerm, unify } from '../term.js';
+import { lexicalValue, stringTerm, unify } from '../term.js';
 
 export const stringBuiltins = {
   register(registry) {
-    for (const name of ['atom_concat', 'str_concat']) registry.add(name, 3, concat(name), { deterministic: true });
-    for (const name of ['contains', 'not_contains', 'matches', 'not_matches']) registry.add(name, 2, contains(name), { deterministic: true });
+    registry.add('str_concat', 3, concat, { deterministic: true });
+    for (const name of ['contains', 'matches', 'not_matches']) registry.add(name, 2, contains(name), { deterministic: true });
   }
 };
 
 
-function concat(name) {
-  return function* ({ goal, env }) {
-    const left = lexicalValue(goal.args[0], env);
-    const right = lexicalValue(goal.args[1], env);
-    if (left == null || right == null) return;
-    const result = name === 'str_concat' ? stringTerm(left + right) : atom(left + right);
-    const next = env.clone();
-    if (unify(goal.args[2], result, next)) yield next;
-  };
+function* concat({ goal, env }) {
+  const left = lexicalValue(goal.args[0], env);
+  const right = lexicalValue(goal.args[1], env);
+  if (left == null || right == null) return;
+  const next = env.clone();
+  if (unify(goal.args[2], stringTerm(left + right), next)) yield next;
 }
 
 function contains(name) {
@@ -29,7 +26,6 @@ function contains(name) {
     const has = haystack.includes(needle);
     const matches = simpleAlternationMatch(haystack, needle);
     const pass = (name === 'contains' && has) ||
-      (name === 'not_contains' && !has) ||
       (name === 'matches' && matches) ||
       (name === 'not_matches' && !matches);
     if (pass) yield env;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.33.4",
+  "version": "1.33.5",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [
@@ -29,6 +29,7 @@
     "eyelang.d.ts",
     "bin",
     "dist",
+    "docs",
     "lib",
     "test",
     "tools",

package/test/eyelang/conformance/README.md

@@ -1,6 +1,6 @@
 # eyelang conformance suite
 
-This directory contains the executable conformance cases for the eyelang language and reference engine. The normative language description is in [`../SPEC.md`](../SPEC.md).
+This directory contains the executable conformance cases for the eyelang language and reference engine. The normative language description is in the [eyelang language reference](../../../docs/eyelang-language-reference.md).
 
 The suite is intentionally file-based so another implementation can run the same programs and compare exact standard output. A case consists of:
 
@@ -20,25 +20,25 @@ npm test
 Run only the conformance suite:
 
 ```sh
-npm run test:conformance
+node test/eyelang/run-conformance.mjs
 ```
 
 Run a single conformance profile directly:
 
 ```sh
-node test/run-conformance.js core
-node test/run-conformance.js extension
+node test/eyelang/run-conformance.mjs core
+node test/eyelang/run-conformance.mjs extension
 ```
 
 The runner executes materialized programs in-process through the public JavaScript API so small conformance cases avoid measuring Node startup overhead.
 
 ## Profiles
 
-`core` covers the portable core language profile from `../SPEC.md`: lexical syntax, facts, definite clauses, first-order terms, lists, conjunction, structured unification through user predicates, left-to-right goal-directed proof search, materialized output, and read-back printing.
+`core` covers the portable core language profile from the [eyelang language reference](../../../docs/eyelang-language-reference.md): lexical syntax, facts, definite clauses, first-order terms, lists, conjunction, structured unification through user predicates, left-to-right goal-directed proof search, materialized output, and read-back printing.
 
-`extension` covers the standard built-in and host behavior exercised by the current reference implementation: arithmetic, comparison, strings, list relations, aggregation, formula-term helpers, number-theory helpers, finite-search helpers, matrix helpers, `memoize/2`, `materialize/2`, and default derived output.
+`extension` covers the standard built-in and host behavior exercised by the current reference implementation: arithmetic, comparison, strings, list relations, aggregation, formula-term helpers, number-theory helpers, finite-search helpers used by the example corpus, matrix helpers, `memoize/2`, `materialize/2`, and default derived output.
 
-The profile name `extension` is a test-suite grouping name. It does not mean that these cases are outside the eyelang specification; most of them correspond to the standard built-in profile and standard host profile in `../SPEC.md`.
+The profile name `extension` is a test-suite grouping name. It does not mean that these cases are outside the eyelang language reference; most of them correspond to the standard built-in profile and standard host profile in the [eyelang language reference](../../../docs/eyelang-language-reference.md).
 
 ## Updating expected output
 

package/test/eyelang/conformance/cases/core/001_fact_output.pl

@@ -1,4 +1,4 @@
-% SPEC 6, 7, 11: facts can be exposed through a materialized derived predicate.
+% Reference 6, 7, 11: facts can be exposed through a materialized derived predicate.
 materialize(parent, 2).
 base_parent(pat, jan).
 parent(X, Y) :- base_parent(X, Y).

package/test/eyelang/conformance/cases/core/002_rule_recursion.pl

@@ -1,4 +1,4 @@
-% SPEC 6, 7: definite clauses, conjunction, and recursive proof search.
+% Reference 6, 7: definite clauses, conjunction, and recursive proof search.
 materialize(ancestor, 2).
 parent(pat, jan).
 parent(jan, emma).

package/test/eyelang/conformance/cases/core/003_terms_and_readback.pl

@@ -1,4 +1,4 @@
-% SPEC 3, 5, 11: scalars, compounds, lists, and read-back printing.
+% Reference 3, 5, 11: scalars, compounds, lists, and read-back printing.
 materialize(value, 2).
 raw_value(atom, pat).
 raw_value(quoted_atom, 'atom with spaces').

package/test/eyelang/conformance/cases/core/004_conjunction_and_parentheses.pl

@@ -1,4 +1,4 @@
-% SPEC 5.5, 7: parenthesized comma terms are conjunctions in goal position.
+% Reference 5.5, 7: parenthesized comma terms are conjunctions in goal position.
 p(a).
 q(a).
 ok(X, yes) :- (p(X), q(X)).

package/test/eyelang/conformance/cases/core/005_list_deconstruction.pl

@@ -1,4 +1,4 @@
-% SPEC 5.4, 12.1: list syntax and unification in rule heads.
+% Reference 5.4, 12.1: list syntax and unification in rule heads.
 first([X | _Rest], X).
 tail([_Head | Tail], Tail).
 answer(first, X) :- first([a, b, c], X).

package/test/eyelang/conformance/cases/core/006_comma_formula_data.pl

@@ -1,4 +1,4 @@
-% SPEC 5.5: comma terms remain data outside goal position.
+% Reference 5.5: comma terms remain data outside goal position.
 record((name(alice, "Alice"), knows(alice, bob))).
 answer(formula, F) :- record(F).
 materialize(answer, 2).

package/test/eyelang/conformance/cases/core/007_anonymous_variables.pl

@@ -1,4 +1,4 @@
-% SPEC 3.4, 5.1, 7.1: each anonymous variable occurrence is fresh.
+% Reference 3.4, 5.1, 7.1: each anonymous variable occurrence is fresh.
 pair(a, one).
 pair(b, two).
 answer(fresh, yes) :- pair(a, _), pair(b, _).

package/test/eyelang/conformance/cases/core/008_graphic_atoms.pl

@@ -1,4 +1,4 @@
-% SPEC 3.5, 5.2, 11: graphic atom constants are scalar terms.
+% Reference 3.5, 5.2, 11: graphic atom constants are scalar terms.
 materialize(value, 2).
 raw_value(hash, #).
 raw_value(arrow, =>).

package/test/eyelang/conformance/cases/core/009_comments_and_whitespace.pl

@@ -1,4 +1,4 @@
-% SPEC 3.2, 3.6: comments are ignored outside quoted text and atoms.
+% Reference 3.2, 3.6: comments are ignored outside quoted text and atoms.
   item(quoted_percent, "% not a comment").    % trailing comment
 item(quoted_atom, 'has % sign').
 answer(K, V) :- item(K, V).

package/test/eyelang/conformance/cases/core/010_variable_scope_and_reuse.pl

@@ -1,4 +1,4 @@
-% SPEC 5.1, 7.1: variable occurrences are scoped per clause and reused within a clause.
+% Reference 5.1, 7.1: variable occurrences are scoped per clause and reused within a clause.
 edge(a, b).
 edge(b, c).
 edge(c, d).

package/test/eyelang/conformance/cases/core/011_predicate_arity.pl

@@ -1,4 +1,4 @@
-% SPEC 6: predicate name and arity both identify a predicate group.
+% Reference 6: predicate name and arity both identify a predicate group.
 p(a).
 p(a, b).
 answer(unary, X) :- p(X).

package/test/eyelang/conformance/cases/core/012_nested_compound_unification.pl

@@ -1,4 +1,4 @@
-% SPEC 5.3, 7.1: unification follows nested compound term structure.
+% Reference 5.3, 7.1: unification follows nested compound term structure.
 fact(pair(a, nested(b, [c, d]))).
 answer(middle, X) :- fact(pair(a, nested(X, [c, d]))).
 answer(list_tail, T) :- fact(pair(a, nested(b, [c | T]))).

package/test/eyelang/conformance/cases/core/013_multiple_clauses_order.pl

@@ -1,4 +1,4 @@
-% SPEC 6, 7: multiple clauses for one predicate are explored as alternatives.
+% Reference 6, 7: multiple clauses for one predicate are explored as alternatives.
 color(red).
 color(blue).
 paint(X) :- color(X).

package/test/eyelang/conformance/cases/core/014_failure_filters_answers.pl

@@ -1,4 +1,4 @@
-% SPEC 7.2: a failing subgoal removes that candidate answer.
+% Reference 7.2: a failing subgoal removes that candidate answer.
 candidate(a).
 candidate(b).
 allowed(a).

package/test/eyelang/conformance/cases/core/015_improper_list_unification.pl

@@ -1,4 +1,4 @@
-% SPEC 5.4: improper list surface syntax unifies with head-tail structure.
+% Reference 5.4: improper list surface syntax unifies with head-tail structure.
 cell([head | tail], head, tail).
 answer(list, L) :- cell(L, head, tail).
 answer(head, H) :- cell([H | tail], H, tail).

package/test/eyelang/conformance/cases/core/016_zero_arity_compound.pl

@@ -1,4 +1,4 @@
-% SPEC 4, 5.3: zero-arity compounds are written and matched with parentheses.
+% Reference 4, 5.3: zero-arity compounds are written and matched with parentheses.
 status(nil(), ok).
 answer(value, X) :- status(X, ok).
 materialize(answer, 2).

package/test/eyelang/conformance/cases/core/017_three_step_recursion.pl

@@ -1,4 +1,4 @@
-% SPEC 7: recursive definite clauses can derive paths beyond one step.
+% Reference 7: recursive definite clauses can derive paths beyond one step.
 link(a, b).
 link(b, c).
 link(c, d).

package/test/eyelang/conformance/cases/core/018_quoted_atom_readback.pl

@@ -1,4 +1,4 @@
-% SPEC 3.5, 11: quoted atoms preserve spaces, quotes, and the empty atom.
+% Reference 3.5, 11: quoted atoms preserve spaces, quotes, and the empty atom.
 symbol('two words').
 symbol('needs''quote').
 symbol('').

package/test/eyelang/conformance/cases/core/019_parenthesized_three_conjuncts.pl

@@ -1,4 +1,4 @@
-% SPEC 5.5, 7: parenthesized comma terms with more than two members are conjunctions as goals.
+% Reference 5.5, 7: parenthesized comma terms with more than two members are conjunctions as goals.
 p(a).
 q(a).
 r(a).

package/test/eyelang/conformance/cases/core/020_nested_list_terms.pl

@@ -1,4 +1,4 @@
-% SPEC 5.3, 5.4: lists may contain structured terms that unify positionally.
+% Reference 5.3, 5.4: lists may contain structured terms that unify positionally.
 node([pair(a, b), pair(c, d)]).
 answer(first_key, X) :- node([pair(X, _), pair(c, d)]).
 answer(second_key, X) :- node([pair(a, b), pair(X, d)]).