eyelang 1.3.3 → 1.3.5

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. The diagnostic is lazy by default; use `{ analyzeNegation: true }` to compute it during parsing or `{ strictNegation: true }` to compute and reject unstratified programs.
+
 ## 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. 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

@@ -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`. This diagnostic is computed lazily when one of those properties or helper methods is first read, or eagerly when parsing with `{ analyzeNegation: true }` or `{ strictNegation: true }`. 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.
@@ -494,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,8 @@ export interface EyelangRunOptions {
   registry?: BuiltinRegistry;
   sourceMetadata?: boolean;
   markRecursive?: boolean;
+  strictNegation?: boolean;
+  analyzeNegation?: boolean;
   [key: string]: unknown;
 }
 
@@ -43,6 +45,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 +73,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 +83,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;

package/package.json

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

package/src/program.js

@@ -14,6 +14,7 @@ export class Program {
       clause.index = index;
       this.indexClause(clause);
     }
+    this._negationAnalysis = null;
     this.applyDeclarations(options);
   }
   static parse(source, options = {}) {
@@ -43,6 +44,7 @@ export class Program {
       mode: null,
       determinism: null,
       recursive: false,
+      negationStratum: null,
     };
     if (arity > 2) {
       for (let left = 0; left < arity; left++) {
@@ -100,6 +102,8 @@ export class Program {
       }
     }
     if (options.markRecursive !== false) this.markRecursivePredicates();
+    if (options.analyzeNegation === true || options.strictNegation === true) this.analyzeNegationStratification();
+    if (options.strictNegation === true) this.assertStratifiedNegation();
   }
   markRecursivePredicates() {
     // Recursion is a group-level diagnostic hint. It is computed from predicate
@@ -136,6 +140,89 @@ 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._negationAnalysis = {
+      dependencies: edges,
+      errors: violations,
+      stratified: violations.length === 0,
+    };
+    return violations;
+  }
+  ensureNegationStratification() {
+    if (!this._negationAnalysis) this.analyzeNegationStratification();
+    return this._negationAnalysis;
+  }
+  get negationDependencies() {
+    return this.ensureNegationStratification().dependencies;
+  }
+  get negationStratificationErrors() {
+    return this.ensureNegationStratification().errors;
+  }
+  get stratifiedNegation() {
+    return this.ensureNegationStratification().stratified;
+  }
+  assertStratifiedNegation() {
+    const violations = this.ensureNegationStratification().errors;
+    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.ensureNegationStratification().stratified;
+  }
+
   hasMaterializeDeclarations() {
     return this.hasMaterialize;
   }
@@ -177,6 +264,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/test/run-regression.mjs

@@ -396,6 +396,66 @@ function apiCases() {
         assertEqual(group.arity, 2, 'group arity');
       },
     },
+    {
+      name: 'program keeps negation diagnostics lazy by default',
+      run: () => {
+        const program = Program.parse('p(a).\nq(?x) :- not(p(?x)).\n');
+        assertEqual(program._negationAnalysis, null, 'analysis starts lazy');
+        assertEqual(program.negationDependencies.length, 1, 'dependency count');
+        assertEqual(program._negationAnalysis !== null, true, 'analysis computed on demand');
+      },
+    },
+    {
+      name: 'analyzeNegation option computes diagnostics eagerly',
+      run: () => {
+        const program = Program.parse('p(a).\nq(?x) :- not(p(?x)).\n', { analyzeNegation: true });
+        assertEqual(program._negationAnalysis !== null, true, 'analysis computed eagerly');
+        assertEqual(program.stratifiedNegation, true, 'stratified negation');
+      },
+    },
+    {
+      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: () => {