eyelang 1.3.1 → 1.3.3

package/README.md

@@ -4,7 +4,7 @@
 [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20761726-blue.svg)](https://doi.org/10.5281/zenodo.20761726)
 
 Eyelang is a small logic programming language for rules, goals, answers, and proofs.
-Its source syntax is Prolog-like Horn-clause syntax with a few deliberate eyelang choices, such as `?x` variables for N3/SPARQL-style readability and explicit `table(path, 2).` declarations for tabled predicates.
+Its source syntax is Prolog-like Horn-clause syntax with a few deliberate eyelang choices, such as `?x` variables for N3/SPARQL-style readability, explicit `table(path, 2).` declarations for tabled predicates, and advisory `mode/3` declarations for host tooling.
 It grew out of logic-language experiments in the EYE/N3 reasoning tradition, but is packaged here as its own project.
 
 ## Install and run

package/docs/guide.md

@@ -568,9 +568,15 @@ Ground facts use a fast path that avoids freshening and copying a rule body. Rec
 table(path, 2).
 ```
 
+Predicates can also carry advisory mode and determinism declarations for documentation and host tooling:
 
-For large programs, keep helper predicates selective, bind arguments early, and declare focused output predicates with `materialize/2` when default output would otherwise solve broad helper goals.
+```eyelang
+mode(path, 2, [in, out]).
+semidet(edge, 2).
+```
+
+For large programs, keep helper predicates selective, bind arguments early, document intended calling patterns with `mode/3` when helpful, and declare focused output predicates with `materialize/2` when default output would otherwise solve broad helper goals.
 
 ## Implementation limits
 
-Eyelang is intentionally smaller than ISO Prolog. It has no operators, zero-arity compound syntax, cut, modules, dynamic database updates, DCGs, or complete ISO library. Negation is negation-as-failure through `not/1`. Search is goal-directed and expected to be finite for the selected output goals. Output explanations are non-normative proof printouts and do not change answer semantics. 
+Eyelang is intentionally smaller than ISO Prolog. It has no operators, zero-arity compound syntax, cut, modules, dynamic database updates, DCGs, or complete ISO library. Arity-zero data is always written and read back as an atom, such as `nil`, never `nil()`. Negation is negation-as-failure through `not/1`. Search is goal-directed and expected to be finite for the selected output goals. Output explanations are non-normative proof printouts and do not change answer semantics. 

package/docs/language-reference.md

@@ -222,7 +222,7 @@ Arity-zero data is written as an atom constant, not as a zero-arity compound:
 value(example, nil).
 ```
 
-The syntax `nil()` is intentionally rejected so eyelang source and read-back output use one representation for arity-zero data.
+The syntax `nil()` is intentionally rejected so eyelang source and read-back output use one representation for arity-zero data. Host APIs SHOULD follow the same rule: constructing a term with an atom name and an empty argument list is canonicalized to the atom constant itself.
 
 ## 5. Terms
 
@@ -473,7 +473,7 @@ Context terms are data representations of atomic formulas and comma conjunctions
 | `holds(?context, ?name, ?args)` | Enumerates context members of any arity, exposing each member as atom constant `?name` plus a proper argument list `?args`. |
 | `functor(?term, ?name, ?arity)` | Decomposes a non-variable term into its name and arity. |
 | `arg(?index, ?term, ?arg)` | Extracts the 1-based argument of a compound term. |
-| `compound_name_arguments(?term, ?name, ?args)` | Decomposes a compound term or constructs one from an atom name and proper argument list. |
+| `compound_name_arguments(?term, ?name, ?args)` | Decomposes a compound term, treats an atom as a zero-argument term, or constructs a term from an atom name and proper argument list. Empty `?args` constructs an atom. |
 
 Example:
 
@@ -483,6 +483,7 @@ holds((ready, name(alice, "Alice"), route(alice, bob, 7)), ?name, ?args).
 functor(route(alice, bob, 7), route, 3).
 arg(2, route(alice, bob, 7), bob).
 compound_name_arguments(?term, route, [alice, bob, 7]).
+compound_name_arguments(nil, nil, []).
 ```
 
 The first goal can yield `holds((name(alice, "Alice"), knows(alice, bob)), name(alice, "Alice")).` The second can yield `holds((ready, name(alice, "Alice"), route(alice, bob, 7)), ready, []).`, `holds((ready, name(alice, "Alice"), route(alice, bob, 7)), name, [alice, "Alice"]).`, and `holds((ready, name(alice, "Alice"), route(alice, bob, 7)), route, [alice, bob, 7]).`
@@ -550,6 +551,33 @@ materialize(reason, 2).
 
 `materialize/2` affects host output selection only; it does not change the logical meaning of the program. Materialized output facts are not asserted as new source facts for subsequent output goals. A host MAY solve several materialized predicates in one solver run, and tabled predicate answers MAY be reused within that run, but this reuse is controlled by `table/2`, not by materialization.
 
+### 11.3 Advisory modes and determinism
+
+```eyelang
+mode(path, 2, [in, out]).
+det(root, 1).
+semidet(edge, 2).
+```
+
+`mode/3`, `det/2`, and `semidet/2` are advisory declarations. They describe a predicate group's intended calling pattern and determinism, but they do not change proof search or answer output. Because they are ordinary facts, programs may also query them.
+
+For `mode(?name, ?arity, ?modes)`, the first argument MUST be an atom constant naming the predicate, the second argument MUST be a non-negative integer arity, and the third argument MUST be a proper list whose length is equal to the arity. Portable mode atoms are:
+
+- `in`: the argument is expected to be supplied by the caller;
+- `out`: the argument is expected to be produced by the predicate;
+- `any`: no portable mode commitment is made for that argument.
+
+`det(?name, ?arity)` declares that a predicate is intended to produce exactly one answer for calls in its documented modes. `semidet(?name, ?arity)` declares that a predicate is intended to produce zero or one answer. This specification does not require runtime enforcement; hosts MAY use these declarations for linting, documentation, indexing decisions, or editor support.
+
+Example:
+
+```eyelang
+mode(member, 2, [out, in]).
+semidet(member, 2).
+```
+
+The example documents the common checking/generation mode where the list is supplied and the member is enumerated. A future linting host could warn if a program calls `member/2` outside that intended mode, but a conforming solver still treats `mode/3` and `semidet/2` as ordinary facts plus metadata.
+
 ## 12. Eyelang Sockets
 
 A **eyelang Socket** is a declared semantic opening in a eyelang program where facts, rules, tools, datasets, or agents can plug in knowledge through an explicit contract while preserving eyelang-readable reasoning and explanations.
@@ -648,6 +676,7 @@ A conforming eyelang implementation supports the standard language described abo
 - the standard built-ins listed in section 9;
 - `table/2` declarations;
 - `materialize/2` declarations;
+- advisory `mode/3`, `det/2`, and `semidet/2` declarations;
 - default derived output;
 - explanation output when the host exposes proof output.
 

package/index.d.ts

@@ -40,6 +40,8 @@ export interface EyelangPredicateGroup {
   argIndexes: unknown[];
   pairIndexes: unknown[];
   tabled: boolean;
+  mode: string[] | null;
+  determinism: 'det' | 'semidet' | null;
   recursive: boolean;
 }
 
@@ -126,6 +128,7 @@ export function variable(name: string): Term;
 export function atom(name: string): Term;
 export function stringTerm(value: string): Term;
 export function numberTerm(value: string | number): Term;
+/** Construct a compound term; an empty argument list is canonicalized to atom(name). */
 export function compound(name: string, args?: EyelangTerm[]): Term;
 export function emptyList(): Term;
 export function cons(head: EyelangTerm, tail: EyelangTerm): Term;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyelang",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "A small Prolog-like logic programming language for rules, goals, answers, and proofs.",
   "type": "module",
   "main": "./index.js",

package/src/builtins/terms.js

@@ -20,7 +20,7 @@ function argReady(goal, env) {
 
 function compoundNameArgumentsReady(goal, env) {
   const term = deref(goal.args[0], env);
-  if (term.type === 'compound') return true;
+  if (term.type === 'compound' || term.type === 'atom') return true;
   return term.type === 'var' && lexicalValue(goal.args[1], env) !== null && properListItems(goal.args[2], env) !== null;
 }
 
@@ -45,9 +45,10 @@ function* argBuiltin({ goal, env }) {
 
 function* compoundNameArguments({ goal, env }) {
   const term = deref(goal.args[0], env);
-  if (term.type === 'compound') {
+  if (term.type === 'compound' || term.type === 'atom') {
     const next = env.clone();
-    if (unify(goal.args[1], atom(term.name), next) && unify(goal.args[2], listFromItems(term.args), next)) yield next;
+    const args = term.type === 'compound' ? term.args : [];
+    if (unify(goal.args[1], atom(term.name), next) && unify(goal.args[2], listFromItems(args), next)) yield next;
     return;
   }
   if (term.type !== 'var') return;

package/src/program.js

@@ -1,6 +1,6 @@
 // Program representation and clause indexing.
 // Indexes are deliberately conservative: they speed up common scalar arguments but never replace unification as the final check.
-import { ATOM, COMPOUND, Env, compound, deref, flattenConjunction, isScalar, termToString } from './term.js';
+import { ATOM, COMPOUND, Env, compound, deref, flattenConjunction, isScalar, properListItems, termToString } from './term.js';
 import { parseClauses } from './parser.js';
 
 export class Program {
@@ -40,6 +40,8 @@ export class Program {
       argIndexes: Array.from({ length: arity }, () => ({ buckets: new Map(), fallback: [] })),
       pairIndexes: [],
       tabled: false,
+      mode: null,
+      determinism: null,
       recursive: false,
     };
     if (arity > 2) {
@@ -70,16 +72,31 @@ export class Program {
   applyDeclarations(options = {}) {
     for (const clause of this.clauses) {
       const h = clause.head;
-      if (clause.body.length !== 0 || h.type !== COMPOUND || h.arity !== 2) continue;
-      const [name, arity] = h.args;
-      if (name.type !== ATOM || arity.type !== 'number') continue;
-      const key = `${name.name}/${Number(arity.name)}`;
-      if (h.name === 'table') {
-        const group = this.groups.get(key);
-        if (group) group.tabled = true;
-      } else if (h.name === 'materialize') {
-        this.hasMaterialize = true;
-        this.materializedGroups.add(key);
+      if (clause.body.length !== 0 || h.type !== COMPOUND) continue;
+
+      if (h.arity === 2) {
+        const indicator = declarationIndicator(h.args[0], h.args[1]);
+        if (!indicator) continue;
+        const group = this.groups.get(indicator.key);
+        if (h.name === 'table') {
+          if (group) group.tabled = true;
+        } else if (h.name === 'materialize') {
+          this.hasMaterialize = true;
+          this.materializedGroups.add(indicator.key);
+        } else if ((h.name === 'det' || h.name === 'semidet') && group) {
+          group.determinism = h.name;
+        }
+        continue;
+      }
+
+      if (h.name === 'mode' && h.arity === 3) {
+        const indicator = declarationIndicator(h.args[0], h.args[1]);
+        if (!indicator) continue;
+        const modes = declarationModes(h.args[2]);
+        if (modes && modes.length === indicator.arity) {
+          const group = this.groups.get(indicator.key);
+          if (group) group.mode = modes;
+        }
       }
     }
     if (options.markRecursive !== false) this.markRecursivePredicates();
@@ -159,6 +176,26 @@ export class Program {
   }
 }
 
+
+function declarationIndicator(name, arity) {
+  if (name?.type !== ATOM || arity?.type !== 'number') return null;
+  if (!/^\d+$/.test(arity.name)) return null;
+  const arityNumber = Number(arity.name);
+  return { name: name.name, arity: arityNumber, key: `${name.name}/${arityNumber}` };
+}
+
+function declarationModes(term) {
+  const items = properListItems(term, new Env());
+  if (!items) return null;
+  const modes = [];
+  for (const item of items) {
+    if (item.type !== ATOM) return null;
+    if (!['in', 'out', 'any'].includes(item.name)) return null;
+    modes.push(item.name);
+  }
+  return modes;
+}
+
 function indexOne(index, arg, clause) {
   if (isScalar(arg)) {
     const bucket = index.buckets.get(arg.name);

package/src/term.js

@@ -21,7 +21,7 @@ export const variable = (name) => new Term(VAR, name);
 export const atom = (name) => new Term(ATOM, name);
 export const stringTerm = (value) => new Term(STRING, value);
 export const numberTerm = (value) => new Term(NUMBER, value);
-export const compound = (name, args = []) => new Term(COMPOUND, name, args);
+export const compound = (name, args = []) => args.length === 0 ? atom(name) : new Term(COMPOUND, name, args);
 export const emptyList = () => atom('[]');
 export const cons = (head, tail) => compound('.', [head, tail]);
 
@@ -113,17 +113,20 @@ export function unify(left, right, env) {
 }
 
 export function cloneTerm(term) {
+  if (term.type === COMPOUND && term.arity === 0) return atom(term.name);
   return new Term(term.type, term.name, term.args.map(cloneTerm));
 }
 
 export function freshTerm(term, suffix) {
   if (term.type === VAR) return variable(`${term.name}#${suffix}`);
+  if (term.type === COMPOUND && term.arity === 0) return atom(term.name);
   return new Term(term.type, term.name, term.args.map((arg) => freshTerm(arg, suffix)));
 }
 
 export function copyResolved(term, env) {
   const resolved = deref(term, env);
   if (resolved.type === VAR) return variable(resolved.name);
+  if (resolved.type === COMPOUND && resolved.arity === 0) return atom(resolved.name);
   return new Term(resolved.type, resolved.name, resolved.args.map((arg) => copyResolved(arg, env)));
 }
 

package/test/conformance/cases/073_term_introspection_edges.eye

@@ -6,5 +6,6 @@ answer(functor_string, pair(?name, ?arity)) :- functor("hi", ?name, ?arity).
 answer(arg_nested, ?x) :- arg(1, path(edge(a, b), c), ?x).
 answer(compose_nested, ?x) :- compound_name_arguments(?x, outer, [inner(a), [b, c]]).
 answer(compose_atom_empty_args, ?x) :- compound_name_arguments(?x, z, []).
+answer(decompose_atom_empty_args, pair(?name, ?args)) :- compound_name_arguments(z, ?name, ?args).
 answer(arg_zero_rejected, ok) :- not(arg(0, edge(a, b), ?x)).
 answer(arg_too_large_rejected, ok) :- not(arg(3, edge(a, b), ?x)).

package/test/conformance/cases/104_mode_determinism_declarations.eye

@@ -0,0 +1,11 @@
+% Reference 11.3: mode/3 and det/2 or semidet/2 are ordinary facts and advisory declarations.
+mode(path, 2, [in, out]).
+det(path, 2).
+semidet(edge, 2).
+materialize(answer, 2).
+edge(a, b).
+path(?x, ?y) :- edge(?x, ?y).
+answer(mode_path, ?modes) :- mode(path, 2, ?modes).
+answer(det_path, ok) :- det(path, 2).
+answer(semidet_edge, ok) :- semidet(edge, 2).
+answer(path, ?y) :- path(a, ?y).

package/test/conformance/expected/073_term_introspection_edges.eye

@@ -4,5 +4,6 @@ answer(functor_string, pair("hi", 0)).
 answer(arg_nested, edge(a, b)).
 answer(compose_nested, outer(inner(a), [b, c])).
 answer(compose_atom_empty_args, z).
+answer(decompose_atom_empty_args, pair(z, [])).
 answer(arg_zero_rejected, ok).
 answer(arg_too_large_rejected, ok).

package/test/conformance/expected/104_mode_determinism_declarations.eye

@@ -0,0 +1,4 @@
+answer(mode_path, [in, out]).
+answer(det_path, ok).
+answer(semidet_edge, ok).
+answer(path, b).

package/test/run-regression.mjs

@@ -337,6 +337,18 @@ function apiCases() {
       },
     },
 
+    {
+      name: 'compound factory canonicalizes zero arity to atoms',
+      run: () => {
+        const nil = compound('nil', []);
+        assertEqual(nil.type, 'atom', 'type');
+        assertEqual(nil.name, 'nil', 'name');
+        assertEqual(nil.arity, 0, 'arity');
+        assertEqual(termToString(nil, new Env(), true), 'nil', 'readback');
+        assertEqual(unify(nil, atom('nil'), new Env()), true, 'unifies with atom');
+      },
+    },
+
     {
       name: 'portable hash helpers match standard vectors',
       run: () => {
@@ -616,6 +628,25 @@ function whiteBoxCases() {
         assertEqual(group.tabled, false, 'memoize/2 is not a table declaration');
       },
     },
+    {
+      name: 'mode and determinism declarations annotate predicate groups',
+      run: () => {
+        const program = Program.parse('mode(path, 2, [in, out]).\ndet(path, 2).\nedge(a, b).\npath(?x, ?y) :- edge(?x, ?y).\n');
+        const group = program.findGroup('path', 2);
+        assertEqual(Boolean(group), true, 'path/2 group exists');
+        assertEqual(group.mode.join(','), 'in,out', 'path/2 mode');
+        assertEqual(group.determinism, 'det', 'path/2 determinism');
+      },
+    },
+    {
+      name: 'semidet declaration annotates predicate groups',
+      run: () => {
+        const program = Program.parse('semidet(edge, 2).\nedge(a, b).\n');
+        const group = program.findGroup('edge', 2);
+        assertEqual(Boolean(group), true, 'edge/2 group exists');
+        assertEqual(group.determinism, 'semidet', 'edge/2 determinism');
+      },
+    },
     {
       name: 'challenging examples keep dynamic-programming predicates tabled',
       run: () => {