eyelang 1.3.1 → 1.3.2

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,8 +568,14 @@ 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
 

package/docs/language-reference.md

@@ -550,6 +550,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 +675,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;
 }
 

package/package.json

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

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/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/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

@@ -616,6 +616,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: () => {