eyelang 1.3.2 → 1.3.4

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, explicit `table(path, 2).` declarations for tabled predicates, and advisory `mode/3` declarations for host tooling.
+Its source syntax is Prolog-like Horn-clause syntax with deliberate eyelang choices, including `?x` variables for N3/SPARQL-style readability, explicit `table(path, 2).` declarations for tabled predicates, advisory `mode/3` declarations for host tooling, and stratified-negation diagnostics for portable `not/1` usage.
 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

@@ -577,6 +577,8 @@ 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.
 
+When using `not/1` over user-defined predicates, keep the dependency graph stratified: negative dependencies should not participate in recursion. The JavaScript API exposes `program.stratifiedNegation`, `program.negationStratificationErrors`, and `program.assertStratifiedNegation()` so host tools can warn or reject programs that rely on unstratified negation.
+
 ## 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
 
@@ -353,6 +353,26 @@ Arithmetic and string built-ins do not introduce a separate semantic universe. T
 
 Negation-as-failure `not(?goal)` is especially operational: it succeeds when the current goal-directed search finds no solution for `?goal`. It is not classical negation and should not be read as adding negative facts to the Herbrand model. Programs using negation SHOULD keep the negated goal sufficiently ground and finite.
 
+### 8.5 Stratified negation
+
+Portable programs using user-defined predicates under `not/1` SHOULD be **stratified**. A program is stratified when no predicate depends negatively on itself, either directly or through a cycle of other predicate dependencies. In a stratified program, predicates can be assigned strata so that positive dependencies stay in the same or a lower stratum and negative dependencies point strictly to a lower stratum.
+
+For example, this is stratified because `open/1` depends negatively on `closed/1`, but `closed/1` does not depend back on `open/1`:
+
+```eyelang
+closed(?x) :- blocked(?x).
+open(?x) :- candidate(?x), not(closed(?x)).
+```
+
+This is not stratified because `p/1` and `q/1` form a cycle that contains a negative dependency:
+
+```eyelang
+p(?x) :- q(?x).
+q(?x) :- not(p(?x)).
+```
+
+The JavaScript implementation records stratification metadata on `Program` instances: `stratifiedNegation`, `negationStratificationErrors`, `negationDependencies`, and per-group `negationStratum`. Embedders that want to reject non-portable negation can parse with `{ strictNegation: true }` or call `program.assertStratifiedNegation()`.
+
 ## 9. Standard built-in predicates
 
 This section specifies the **standard built-ins** of the Eyelang language. An implementation that claims support for this standard built-in profile MUST implement the predicates in this section with the meanings described here.
@@ -473,7 +493,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 +503,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]).`
@@ -493,7 +514,7 @@ The first goal can yield `holds((name(alice, "Alice"), knows(alice, bob)), name(
 
 | Built-in | Meaning |
 |---|---|
-| `not(?goal)` | Negation as failure. Succeeds when `?goal` has no solution. |
+| `not(?goal)` | Negation as failure. Succeeds when `?goal` has no solution. Portable user-defined negation should be stratified. |
 | `once(?goal)` | Succeeds with at most the first solution of `?goal`. |
 | `forall(?generator, ?test)` | Succeeds when every solution of `?generator` also satisfies `?test`; succeeds vacuously when `?generator` has no solutions. |
 

package/index.d.ts

@@ -11,6 +11,7 @@ export interface EyelangRunOptions {
   registry?: BuiltinRegistry;
   sourceMetadata?: boolean;
   markRecursive?: boolean;
+  strictNegation?: boolean;
   [key: string]: unknown;
 }
 
@@ -43,6 +44,7 @@ export interface EyelangPredicateGroup {
   mode: string[] | null;
   determinism: 'det' | 'semidet' | null;
   recursive: boolean;
+  negationStratum: number | null;
 }
 
 export type EyelangTerm = Term | { type: string; name: string; args?: EyelangTerm[]; arity?: number };
@@ -70,6 +72,9 @@ export class Program {
   groups: Map<string, EyelangPredicateGroup>;
   materializedGroups: Set<string>;
   hasMaterialize: boolean;
+  negationDependencies: Array<{ from: string; to: string; negative: boolean }>;
+  negationStratificationErrors: Array<{ from: string; to: string }>;
+  stratifiedNegation: boolean;
   static parse(source: string, options?: EyelangRunOptions): Program;
   static parseSources(sources?: Array<string | EyelangSourcePart>, options?: EyelangRunOptions): Program;
   makeGroup(name: string, arity: number): EyelangPredicateGroup;
@@ -77,6 +82,9 @@ export class Program {
   findGroup(name: string, arity: number): EyelangPredicateGroup | null;
   applyDeclarations(options?: EyelangRunOptions): void;
   markRecursivePredicates(): void;
+  analyzeNegationStratification(): Array<{ from: string; to: string }>;
+  assertStratifiedNegation(): true;
+  isStratifiedNegation(): boolean;
   hasMaterializeDeclarations(): boolean;
   groupIsMaterialized(group: EyelangPredicateGroup): boolean;
   groupHasRule(group: EyelangPredicateGroup): boolean;
@@ -128,6 +136,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.2",
+  "version": "1.3.4",
   "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

@@ -43,6 +43,7 @@ export class Program {
       mode: null,
       determinism: null,
       recursive: false,
+      negationStratum: null,
     };
     if (arity > 2) {
       for (let left = 0; left < arity; left++) {
@@ -100,6 +101,8 @@ export class Program {
       }
     }
     if (options.markRecursive !== false) this.markRecursivePredicates();
+    this.analyzeNegationStratification();
+    if (options.strictNegation === true) this.assertStratifiedNegation();
   }
   markRecursivePredicates() {
     // Recursion is a group-level diagnostic hint. It is computed from predicate
@@ -136,6 +139,74 @@ export class Program {
       group.recursive = recursive;
     }
   }
+
+  analyzeNegationStratification() {
+    // Stratified negation is a portability diagnostic. A program is stratified
+    // when no predicate depends negatively on itself, directly or indirectly.
+    const groups = [...this.groups.values()];
+    const groupKeys = new Map(groups.map((group) => [group, `${group.name}/${group.arity}`]));
+    const groupByKey = new Map(groups.map((group) => [`${group.name}/${group.arity}`, group]));
+    const indexByKey = new Map(groups.map((group, i) => [`${group.name}/${group.arity}`, i]));
+    const edges = [];
+
+    for (const group of groups) {
+      const from = groupKeys.get(group);
+      for (const clause of group.clauses) {
+        for (const goal of clause.body) {
+          for (const dep of collectGoalDependencies(goal, false)) {
+            if (!groupByKey.has(dep.key)) continue;
+            edges.push({ from, to: dep.key, negative: dep.negative });
+          }
+        }
+      }
+    }
+
+    const adjacency = groups.map(() => []);
+    for (const edge of edges) {
+      const from = indexByKey.get(edge.from);
+      const to = indexByKey.get(edge.to);
+      if (from == null || to == null) continue;
+      adjacency[from].push(to);
+    }
+
+    const sccs = stronglyConnectedComponents(adjacency);
+    const componentByIndex = new Map();
+    for (let component = 0; component < sccs.length; component++) {
+      for (const index of sccs[component]) componentByIndex.set(index, component);
+    }
+
+    const violations = [];
+    const seen = new Set();
+    for (const edge of edges) {
+      if (!edge.negative) continue;
+      const from = indexByKey.get(edge.from);
+      const to = indexByKey.get(edge.to);
+      if (from == null || to == null) continue;
+      if (componentByIndex.get(from) !== componentByIndex.get(to)) continue;
+      const key = `${edge.from}->${edge.to}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      violations.push({ from: edge.from, to: edge.to });
+    }
+
+    const strata = computeNegationStrata(groups, edges, indexByKey);
+    for (const group of groups) group.negationStratum = strata.get(groupKeys.get(group)) ?? null;
+
+    this.negationDependencies = edges;
+    this.negationStratificationErrors = violations;
+    this.stratifiedNegation = violations.length === 0;
+    return violations;
+  }
+  assertStratifiedNegation() {
+    const violations = this.negationStratificationErrors ?? this.analyzeNegationStratification();
+    if (violations.length === 0) return true;
+    const details = violations.map((edge) => `${edge.from} depends negatively on ${edge.to}`).join('; ');
+    throw new Error(`unstratified negation: ${details}`);
+  }
+  isStratifiedNegation() {
+    return this.stratifiedNegation !== false;
+  }
+
   hasMaterializeDeclarations() {
     return this.hasMaterialize;
   }
@@ -177,6 +248,92 @@ export class Program {
 }
 
 
+
+function collectGoalDependencies(goal, negated) {
+  if (goal.type !== COMPOUND) return [];
+  if (goal.name === ',' && goal.arity === 2) {
+    return [
+      ...collectGoalDependencies(goal.args[0], negated),
+      ...collectGoalDependencies(goal.args[1], negated),
+    ];
+  }
+  if (goal.name === 'not' && goal.arity === 1) {
+    return collectGoalDependencies(goal.args[0], !negated);
+  }
+  if (goal.name === 'once' && goal.arity === 1) {
+    return collectGoalDependencies(goal.args[0], negated);
+  }
+  if (goal.name === 'forall' && goal.arity === 2) {
+    return [
+      ...collectGoalDependencies(goal.args[0], negated),
+      ...collectGoalDependencies(goal.args[1], negated),
+    ];
+  }
+  return [{ key: `${goal.name}/${goal.arity}`, negative: negated }];
+}
+
+function stronglyConnectedComponents(adjacency) {
+  let index = 0;
+  const stack = [];
+  const onStack = new Set();
+  const indexes = new Map();
+  const lowlinks = new Map();
+  const components = [];
+
+  function visit(v) {
+    indexes.set(v, index);
+    lowlinks.set(v, index);
+    index++;
+    stack.push(v);
+    onStack.add(v);
+
+    for (const w of adjacency[v]) {
+      if (!indexes.has(w)) {
+        visit(w);
+        lowlinks.set(v, Math.min(lowlinks.get(v), lowlinks.get(w)));
+      } else if (onStack.has(w)) {
+        lowlinks.set(v, Math.min(lowlinks.get(v), indexes.get(w)));
+      }
+    }
+
+    if (lowlinks.get(v) === indexes.get(v)) {
+      const component = [];
+      while (true) {
+        const w = stack.pop();
+        onStack.delete(w);
+        component.push(w);
+        if (w === v) break;
+      }
+      components.push(component);
+    }
+  }
+
+  for (let v = 0; v < adjacency.length; v++) {
+    if (!indexes.has(v)) visit(v);
+  }
+  return components;
+}
+
+function computeNegationStrata(groups, edges, indexByKey) {
+  const strata = new Map(groups.map((group) => [`${group.name}/${group.arity}`, 0]));
+  if (groups.length === 0) return strata;
+
+  for (let pass = 0; pass < groups.length; pass++) {
+    let changed = false;
+    for (const edge of edges) {
+      if (!indexByKey.has(edge.from) || !indexByKey.has(edge.to)) continue;
+      const fromStratum = strata.get(edge.from) ?? 0;
+      const required = (strata.get(edge.to) ?? 0) + (edge.negative ? 1 : 0);
+      if (fromStratum < required) {
+        strata.set(edge.from, required);
+        changed = true;
+      }
+    }
+    if (!changed) return strata;
+  }
+  return new Map(groups.map((group) => [`${group.name}/${group.arity}`, null]));
+}
+
 function declarationIndicator(name, arity) {
   if (name?.type !== ATOM || arity?.type !== 'number') return null;
   if (!/^\d+$/.test(arity.name)) return null;

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/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/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: () => {
@@ -384,6 +396,49 @@ function apiCases() {
         assertEqual(group.arity, 2, 'group arity');
       },
     },
+    {
+      name: 'program reports stratified negation metadata',
+      run: () => {
+        const program = Program.parse(`
+materialize(open, 1).
+candidate(a).
+blocked(b).
+closed(?x) :- blocked(?x).
+open(?x) :- candidate(?x), not(closed(?x)).
+`);
+        assertEqual(program.isStratifiedNegation(), true, 'stratified negation');
+        assertEqual(program.negationStratificationErrors.length, 0, 'stratification errors');
+        assertEqual(program.findGroup('closed', 1).negationStratum, 0, 'closed stratum');
+        assertEqual(program.findGroup('open', 1).negationStratum, 1, 'open stratum');
+      },
+    },
+    {
+      name: 'program detects unstratified negation cycles',
+      run: () => {
+        const program = Program.parse('p(?x) :- q(?x).\nq(?x) :- not(p(?x)).\n');
+        assertEqual(program.isStratifiedNegation(), false, 'unstratified negation');
+        assertEqual(program.negationStratificationErrors.length, 1, 'stratification error count');
+        assertEqual(program.negationStratificationErrors[0].from, 'q/1', 'error source');
+        assertEqual(program.negationStratificationErrors[0].to, 'p/1', 'error target');
+        let threw = false;
+        try { program.assertStratifiedNegation(); } catch (err) {
+          threw = true;
+          assertIncludes(err.message, 'unstratified negation', 'error message');
+        }
+        assertEqual(threw, true, 'assertion throws');
+      },
+    },
+    {
+      name: 'strictNegation option rejects unstratified programs',
+      run: () => {
+        let threw = false;
+        try { Program.parse('p(?x) :- not(p(?x)).\n', { strictNegation: true }); } catch (err) {
+          threw = true;
+          assertIncludes(err.message, 'p/1 depends negatively on p/1', 'error message');
+        }
+        assertEqual(threw, true, 'strict negation throws');
+      },
+    },
     {
       name: 'program and solver public classes',
       run: () => {