eyelang 1.3.0 → 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

@@ -2,7 +2,7 @@
 
 This guide introduces Eyelang, a small Horn-clause language and engine whose source syntax is Prolog-like but deliberately its own compact language for rules, goals, answers, and proofs. Eyelang works over ordinary terms, lists, arithmetic, strings, and finite search. Run it with the `eyelang` CLI, or use `node bin/eyelang.js` when working directly from a source checkout.
 
-Programs write relations directly, for example `ancestor(pat, emma)` or `status(case1, accepted)`. Eyelang output is ordinary Eyelang syntax: by default, the CLI materializes selected answer facts and prints those facts only. Pass `--proof` (or `-p`) when you also want each answer followed by a `why/2` explanation fact that records the proof. Programs may add `materialize/2` declarations such as `materialize(answer, 2).` to focus output on selected predicates.
+Programs write relations directly, for example `ancestor(pat, emma)` or `status(case1, accepted)`. Absolute IRI atoms can be written explicitly with angle brackets, for example `<https://schema.org/name>`, when a program needs web identifiers without prefix declarations. Eyelang output is ordinary Eyelang syntax: by default, the CLI materializes selected answer facts and prints those facts only. Pass `--proof` (or `-p`) when you also want each answer followed by a `why/2` explanation fact that records the proof. Programs may add `materialize/2` declarations such as `materialize(answer, 2).` to focus output on selected predicates.
 
 
 For the normative language definition, including lexical syntax, terms, clauses, goals, built-ins, `table/2`, `materialize/2`, and conformance boundaries, read the [Eyelang language reference](language-reference.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

@@ -138,7 +138,7 @@ Each `?_` anonymous variable occurrence is fresh. A bare `_` is not a variable i
 
 ### 3.5 Atom constants
 
-A plain atom constant starts with a lowercase ASCII letter and is followed by zero or more ASCII letters, digits, or underscores. A dot is not part of a plain atom; dotted web spaces such as `'be.ugent'` or `'org.schema'` MUST be quoted if they are meant as one atom constant. Names such as `a-b` or `http://example` MUST also be quoted if they are meant as one atom constant:
+A plain atom constant starts with a lowercase ASCII letter and is followed by zero or more ASCII letters, digits, or underscores. A dot is not part of a plain atom; dotted web spaces such as `'be.ugent'` or `'org.schema'` MUST be quoted if they are meant as one atom constant. Names such as `a-b` MUST also be quoted if they are meant as one atom constant:
 
 ```eyelang
 pat
@@ -148,9 +148,18 @@ case_123
 'org.schema'
 'eyereasoner.github'
 'a-b'
-'http://example'
 ```
 
+Absolute IRI atom constants MAY also be written between angle brackets. The content must be an absolute IRI-like lexical value with a scheme such as `https:` or `urn:`. Eyelang stores the content as the atom value and prints absolute IRI atoms with angle brackets on read-back:
+
+```eyelang
+<https://example.org/alice>
+<urn:example:bob>
+triple(<https://example.org/alice>, <https://schema.org/name>, "Alice").
+```
+
+Quoted absolute IRI atoms remain valid input, but read-back normalizes them to angle-bracket syntax. For example, `'https://example.org/alice'` prints as `<https://example.org/alice>`.
+
 A quoted atom constant is enclosed in single quotes. A single quote inside a quoted atom constant is represented by doubling it:
 
 ```eyelang
@@ -165,6 +174,8 @@ A graphic atom constant is one or more graphic characters from this set:
 #$&*+-/<=>?@^~\
 ```
 
+Angle-bracket IRI syntax is recognized only for absolute IRI-like contents. Graphic atoms such as `<=>`, `<`, and `>=` remain graphic atoms.
+
 ### 3.6 Strings
 
 A string is enclosed in double quotes. The implementation supports common escapes such as `\n`, `\t`, `\"`, and `\\`.
@@ -539,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.
@@ -637,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.
 
@@ -659,7 +698,7 @@ eyelang source is intended to be familiar to Prolog readers, but eyelang is not
 - no variables in functor or predicate position;
 - no occurs check in unification.
 
-Programs intended to be portable to eyelang SHOULD use `?` variables, avoid ISO-specific syntax, and keep terms explicit. Atom names that are not plain lowercase-starting names or graphic atom tokens SHOULD be written as quoted atoms, for example `'a-b'`.
+Programs intended to be portable to eyelang SHOULD use `?` variables, avoid ISO-specific syntax, and keep terms explicit. Atom names that are not plain lowercase-starting names, graphic atom tokens, or angle-bracket absolute IRI atoms SHOULD be written as quoted atoms, for example `'a-b'`.
 
 ## 16. Examples
 

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.0",
+  "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/parser.js

@@ -7,6 +7,22 @@ const TOK = {
   LPAREN: '(', RPAREN: ')', LBRACKET: '[', RBRACKET: ']', COMMA: ',', BAR: '|', DOT: '.', IF: ':-'
 };
 
+function isAbsoluteIriText(text) {
+  return /^[A-Za-z][A-Za-z0-9+.-]*:[^\s<>"'{}|\\^`]*$/.test(text);
+}
+
+function hasAngleIriToken(source, pos) {
+  if (source[pos] !== '<') return false;
+  let text = '';
+  for (let i = pos + 1; i < source.length; i++) {
+    const ch = source[i];
+    if (ch === '>') return text.length > 0 && isAbsoluteIriText(text);
+    if (ch === '\n' || ch === '\r' || /\s/.test(ch) || ch === '<') return false;
+    text += ch;
+  }
+  return false;
+}
+
 function isWhitespaceCode(code) {
   return code === 32 || code === 9 || code === 10 || code === 13 || code === 12 || code === 11;
 }
@@ -97,6 +113,18 @@ class Parser {
     }
     if (ch === ':') throw new Error('colon names are not supported; use name or prefix_name');
 
+    if (hasAngleIriToken(this.source, this.pos)) {
+      this.take(); // <
+      let text = '';
+      while (true) {
+        if (!this.peek()) throw new Error(`parse line ${line}: unterminated IRI`);
+        const value = this.take();
+        if (value === '>') break;
+        text += value;
+      }
+      return { type: TOK.ATOM, text, line };
+    }
+
     if (ch === '"' || ch === "'") {
       const quote = this.take();
       let text = '';

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

@@ -135,6 +135,14 @@ export function termIsGround(term, env = new Env()) {
 
 const graphicAtomChars = new Set('#$&*+-/<=>?@^~\\'.split(''));
 
+function isAbsoluteIriText(text) {
+  return /^[A-Za-z][A-Za-z0-9+.-]*:[^\s<>"'{}|\\^`]*$/.test(text);
+}
+
+function writeAngleIri(name) {
+  return `<${name}>`;
+}
+
 function atomNeedsQuotes(name) {
   if (!name) return true;
   if (name === '[]') return false;
@@ -156,6 +164,7 @@ function quoteAtom(name) {
 }
 
 function writeAtom(name) {
+  if (isAbsoluteIriText(name)) return writeAngleIri(name);
   return atomNeedsQuotes(name) ? quoteAtom(name) : name;
 }
 

package/test/conformance/cases/103_angle_iri_atoms.eye

@@ -0,0 +1,7 @@
+% Reference 3.5: absolute IRIs may be written as angle-bracket atom constants.
+materialize(iri_subject, 1).
+materialize(iri_object, 1).
+triple(<https://example.org/alice>, <https://schema.org/name>, "Alice").
+triple(<urn:example:bob>, <https://schema.org/knows>, <https://example.org/alice>).
+iri_subject(?iri) :- triple(?iri, ?_, ?_).
+iri_object(?iri) :- triple(?_, <https://schema.org/knows>, ?iri).

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/103_angle_iri_atoms.eye

@@ -0,0 +1,3 @@
+iri_subject(<https://example.org/alice>).
+iri_subject(<urn:example:bob>).
+iri_object(<https://example.org/alice>).

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

@@ -529,6 +529,27 @@ function whiteBoxCases() {
         assertEqual(termToString(clauses[0].head, new Env(), true), "p(web('be.ugent', josd), 'org.schema')", 'head');
       },
     },
+    {
+      name: 'parser accepts angle-bracket absolute IRI atoms',
+      run: () => {
+        const clauses = parseProgramText('p(<https://example.org/alice>, <urn:example:bob>).\n');
+        assertEqual(termToString(clauses[0].head, new Env(), true), 'p(<https://example.org/alice>, <urn:example:bob>)', 'head');
+      },
+    },
+    {
+      name: 'readback prints absolute IRI atoms with angle brackets',
+      run: () => {
+        const clauses = parseProgramText("p('https://example.org/alice').\n");
+        assertEqual(termToString(clauses[0].head, new Env(), true), 'p(<https://example.org/alice>)', 'head');
+      },
+    },
+    {
+      name: 'angle IRI syntax does not steal graphic atom syntax',
+      run: () => {
+        const clauses = parseProgramText('p(<=>).\n');
+        assertEqual(termToString(clauses[0].head, new Env(), true), 'p(<=>)', 'head');
+      },
+    },
     {
       name: 'list construction round-trips through properListItems',
       run: () => {
@@ -595,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: () => {