eyemind 0.1.30 → 0.1.32

package/README.md

@@ -18,7 +18,7 @@ JavaScript library, and a browser application, with no dependencies.
 - **[Examples](https://eyereasoner.github.io/eyemind/examples/)**:
   94 runnable programs, each with a card deck and saved conclusions, proofs
   and check reports.
-- **[Conformance suite](conformance/)**: 398 cases that test any
+- **[Conformance suite](conformance/)**: 400 cases that test any
   implementation of the specification through its command line.
 
 ```js

package/SPEC.md

@@ -2,7 +2,7 @@
 
 ```text
 Title:      The eyemind Rule Language and Proof Format
-Version:    eyemind 0.1.30
+Version:    eyemind 0.1.32
 Status:     Informational
 Author:     Jos De Roo, KNoWS office of IDLab, Ghent University - imec
 Repository: https://github.com/eyereasoner/eyemind
@@ -22,7 +22,7 @@ command line.
 ## Status of This Memo
 
 This document is not an Internet Standards Track specification. It describes
-the language and formats as implemented by eyemind 0.1.30, for readers who want
+the language and formats as implemented by eyemind 0.1.32, for readers who want
 to write programs, produce or consume proofs and reports, or implement a
 compatible reasoner or checker. Where this document and the implementation
 disagree, that is a defect in one of them.
@@ -506,16 +506,20 @@ concluded:
 
 - a head variable the solution leaves unbound is bound to a **Skolem term**
   `skolem(Rule, Variable, Arguments)`: `Rule` is the clause number of the
-  rule, `Variable` the variable's name as the program writes it (an
-  anonymous one as `_0`, `_1`, ..., Section 4.4), and `Arguments` the list of
+  rule, `Variable` the name of the head variable the term stands for, as the
+  program writes it (an anonymous one as `_0`, `_1`, ..., Section 4.4), and
+  `Arguments` the list of
   the ground values the solution gives the heads' other variables, in order
   of their first occurrence in the heads. A Skolem term is thus a function of
   the activation: the rule and the instance of its heads. The same activation
   gives the same terms, in any round and in any run, and different
   activations give different terms; variables shared between heads stay
-  shared. A variable that a value of the solution brought in, rather than a
-  head variable, is named after its own variable, followed by `1`, `2`, ...
-  when that name is taken. A rule that keeps meeting new activations does
+  shared. When several head variables stand for one term, the first of them
+  in the heads names it, whichever way unification bound them. A variable
+  that a value of the solution brought in, which no head variable stands
+  for, keeps its own name when no other term of the activation has it; the
+  others take that name followed by the first of `1`, `2`, ... that is
+  free, in order of first occurrence in the heads. A rule that keeps meeting new activations does
   not terminate (Section 7.3). Derived facts other than scoped inspection
   patterns (Section 4.7) are therefore ground. A
   checker verifies the Skolem terms of a proof (C8, Section 11.9);
@@ -578,8 +582,12 @@ An explicit goal MAY ask for an activation. Activations remain available as
 premises and proof steps; the library's `inferred` list omits them. The
 `derived` statistic counts them as facts added during reasoning.
 
-The output of a run is the canonical text (Section 8) of each conclusion,
-one per line.
+The output of a run is a comment line saying which of these the conclusions
+are, followed by the canonical text (Section 8) of each conclusion, one per
+line. The comment MUST say when the run halted, when the conclusions answer
+goals, when they answer `query()` rules, or when they are derived facts, and
+MUST say so when there are none. Comments are informative and MAY be worded
+differently; they are ignored when the output is read (Section 9).
 
 ### 7.7 Proof recording
 
@@ -685,12 +693,18 @@ string. Reading the canonical text of a term MUST give the term back.
 
 A proof document is a document (Section 9) holding, in this order:
 
-1. the conclusions of the run (Section 7.6), one per line;
+1. the output of the run (Section 7.6): its comment line, then its
+   conclusions, one per line;
 2. an empty line;
-3. one `clause(N, Display)` per program clause the proof cites, by
+3. when the proof cites any clause, a comment line introducing the clauses,
+   then one `clause(N, Display)` per program clause the proof cites, by
    increasing `N`;
 4. an empty line;
-5. one `step(Goal, By, Bindings, Uses)` per justified goal.
+5. when there are steps, comment lines saying what a step records, then one
+   `step(Goal, By, Bindings, Uses)` per justified goal.
+
+Comments are informative and MAY be worded differently; they are ignored when
+the document is read.
 
 A checker MUST treat every statement that is neither `clause/2` nor `step/4`
 as a claim, whatever its position.
@@ -806,9 +820,12 @@ forbidden ("strict"), each `'absent'` or `'collected'` step fails C5.
 
 A trusted boundary cannot be proved, but the evidence at hand can refute it.
 The evidence for a goal is: when the goal is a ground primitive, the goal
-itself if it holds; when it is a control, none, and the boundary is left
-undecided; otherwise the program's facts and the goals of the document's
-steps with the same name and arity.
+itself if it holds, and otherwise the recomputed fact that it fails; when it
+is a control, none, and the boundary is left undecided; otherwise the
+program's facts and the goals of the document's steps with the same name and
+arity. A goal of the last kind **has evidence** only when there is at least
+one such fact or step goal; with none, nothing could refute the boundary, and
+it is left undecided.
 
 - An absence `not(G)` is decided when `G` is a single goal, or a ground
   conjunction, whose every goal has evidence. It fails C6 when every goal of
@@ -838,8 +855,7 @@ value gives an instance of the rule, so for a `clause(N)` step citing a
 forward rule, under the substitution of C1, each such variable `V` MUST be
 bound to `skolem(N, Name, Args)`, where:
 
-- `Name` is the name of `V` as the program writes it, or that name followed
-  by digits (Section 7.2);
+- `Name` is the name of `V` as the program writes it (Section 7.2);
 - `Args` is the same for every such variable of the step, and is the list of
   the values of the heads' variables, in order of their first occurrence in
   the heads, that are ground and contain no Skolem term `skolem(N, _, Args)`:
@@ -1039,7 +1055,7 @@ conclusions and proof documents in the canonical text, and checks every proof
 it produces as Section 11 describes. A conforming **checker** implements
 Sections 9, 11 and 12 and does not depend on a reasoner. For the same
 program, a conforming reasoner and checker MUST produce the same
-conclusions, proof documents and reports as eyemind 0.1.30, byte for byte,
+conclusions, proof documents and reports as eyemind 0.1.32, byte for byte,
 except for comments and the `Detail` texts of failures (Section 12), the internal names of
 variables where Section 3 says so, and where the host's floating-point
 library functions (`exp`, `log`, the trigonometric and hyperbolic functions,
@@ -1094,6 +1110,7 @@ query(type(X, Y))
 Its conclusions:
 
 ```js
+// Answers: each instance of a query() that holds.
 type('socrates', 'mortal')
 type('socrates', 'human')
 ```
@@ -1101,13 +1118,17 @@ type('socrates', 'human')
 Its proof document (Section 10):
 
 ```js
+// Answers: each instance of a query() that holds.
 type('socrates', 'mortal')
 type('socrates', 'human')
 
+// Clauses: the program clauses the steps cite, by clause number.
 clause(1, fact(type('socrates', 'human')))
 clause(2, fact(subclass_of('human', 'mortal')))
 clause(3, implies([type(S, A), subclass_of(A, B)], type(S, B)))
 
+// Steps: each goal, what justifies it (a clause, a builtin, a control, or an
+// absence or collection taken on trust), the bindings and the goals it uses.
 step(type('socrates', 'mortal'), clause(3), {S: 'socrates', A: 'human', B: 'mortal'}, [type('socrates', 'human'), subclass_of('human', 'mortal')])
 step(type('socrates', 'human'), clause(1), {}, [])
 step(subclass_of('human', 'mortal'), clause(2), {}, [])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyemind",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "description": "A dependency-free JavaScript rule language with forward and backward reasoning and checkable proofs.",
   "type": "module",
   "main": "./src/index.js",

package/src/cli.js

@@ -74,6 +74,12 @@ export function main(argv, io) {
         i++;
         if (i >= argv.length) throw new UsageError(`${arg} needs a value`);
         const value = argv[i];
+        // An option in the value's place means the value was left out, as in
+        // --check-proof --strict-proof proof.js; reading the option as a file
+        // name would only fail later with a puzzling message.
+        if (/^--./.test(value) || ['-p', '-c', '-h'].includes(value)) {
+          throw new UsageError(`${arg} needs a value right after it, not the option ${value}`);
+        }
         if (arg === '--check-proof') {
           proofFile = value;
         } else if (arg === '--goal') {

package/src/engine.js

@@ -615,11 +615,9 @@ export class Solver {
   directKeys(clause) {
     if (this.direct.has(clause.id)) return this.direct.get(clause.id);
     let keys = [];
+    // A forward rule's body goals are all callable: Program rejects numbers,
+    // and stratification rejects variables a forward rule can reach.
     for (const goal of clause.body) {
-      if (!isCallable(goal)) {
-        keys = null;
-        break;
-      }
       const goalKey = key(goal);
       if (PRIMITIVE_KEYS.has(goalKey) || INSPECTION_KEYS.has(goalKey) || goalKey === 'not/1' || goalKey === 'findall/3') {
         keys.push(null);
@@ -808,22 +806,41 @@ export function skolemTerms(clause, head, unresolved, env, context = null) {
     if (isGround(value)) values.push(value);
   }
   const argumentsList = listFromItems(values);
-  const names = [];
-  for (const variable of unresolved.values()) {
-    // Each variable is named as the program names it; a variable that a value
-    // of the solution brought in may share a name, so it gets a number to
-    // keep the terms apart.
+  const sourceName = (variable) => {
     const hash = variable.name.indexOf('#');
-    const base = hash < 0 ? variable.name : variable.name.slice(0, hash);
-    let name = base;
-    let number = 1;
-    while (names.includes(name)) {
-      name = `${base}${number}`;
-      number++;
+    return hash < 0 ? variable.name : variable.name.slice(0, hash);
+  };
+  // A term a head variable stands for is named after that variable, the
+  // first in the heads when several share it, whichever way unification
+  // bound them. A variable a value of the solution brought in keeps its own
+  // name when that is free, and otherwise gets the first free numbered one.
+  const named = new Map();
+  for (const variable of variables(head).values()) {
+    const value = copyResolved(variable, env);
+    if (value instanceof Var && unresolved.has(value.name) && !named.has(value.name)) {
+      named.set(value.name, sourceName(variable));
     }
-    names.push(name);
   }
-  return names.map((name) => new Struct('skolem', [BigInt(clause.id), name, argumentsList]));
+  const taken = new Set(named.values());
+  const clashing = [];
+  for (const variable of unresolved.values()) {
+    if (named.has(variable.name)) continue;
+    const base = sourceName(variable);
+    if (taken.has(base)) {
+      clashing.push(variable);
+    } else {
+      taken.add(base);
+      named.set(variable.name, base);
+    }
+  }
+  for (const variable of clashing) {
+    const base = sourceName(variable);
+    let name = base;
+    for (let number = 1; taken.has(name); number++) name = `${base}${number}`;
+    taken.add(name);
+    named.set(variable.name, name);
+  }
+  return [...unresolved.keys()].map((name) => new Struct('skolem', [BigInt(clause.id), named.get(name), argumentsList]));
 }
 
 // What a run concluded. answers are the conclusions as printable text and
@@ -869,6 +886,20 @@ export function run(program, { goal = null, goals = null, proof = false, maxDept
   }
 }
 
+// The comment that opens a run's output and proof: what its conclusions are
+// (SPEC Section 7.6), and that there are none when there are none.
+function conclusionsHeading(kind, count) {
+  if (kind === 'halted') return "// Halted: a contradiction() holds; the facts derived until then, ending with 'false'.";
+  if (kind === 'goals') {
+    return count ? '// Answers: each instance of a goal that holds.' : '// No answers: no instance of a goal holds.';
+  }
+  if (kind === 'queries') {
+    return count ? '// Answers: each instance of a query() that holds.' : '// No answers: no query() instance holds.';
+  }
+  return count ? '// Conclusions: the facts the program derives, in the order derived.'
+    : '// No conclusions: the program derives no facts.';
+}
+
 function reason(program, goalInputs, options) {
   const solver = new Solver(program, options);
   const goals = goalInputs.map(goalTerm);
@@ -906,6 +937,9 @@ function reason(program, goalInputs, options) {
       claims.push(node.goal);
     }
   }
+  const heading = conclusionsHeading(solver.haltCode !== null ? 'halted'
+    : goals.length ? 'goals'
+      : program.forward.some((clause) => clause.heads.includes('true')) ? 'queries' : 'derived', claims.length);
   // Variables are named A, B, ... in the order the conclusions show them; the
   // bindings of each answer name them as its conclusion does.
   const lettering = new Lettering();
@@ -915,7 +949,7 @@ function reason(program, goalInputs, options) {
     for (const [name, value] of answer) out[name] = write(value, null, lettering);
     return out;
   });
-  const rendered = options.proof ? renderProof(program, claims, roots, true) : null;
+  const rendered = options.proof ? renderProof(program, claims, roots, true, heading) : null;
   const document = rendered !== null ? rendered[0] : null;
   // A rule that reports a claim is used by it, though a proof records only
   // the claim's support.
@@ -939,7 +973,7 @@ function reason(program, goalInputs, options) {
     derived: solver.derived,
     clausesUsed: used !== null ? [...used].sort((a, b) => a - b) : null,
     clausesBehindBoundaries: behind,
-    stdout: document !== null ? document : answers.map((answer) => `${answer}\n`).join(''),
+    stdout: document !== null ? document : [heading, ...answers].map((line) => `${line}\n`).join(''),
     proof: document,
     proofReport: report,
     stats: solver.stats,

package/src/program.js

@@ -114,6 +114,11 @@ export class Program {
                               'write query(Premise) or contradiction(Premise)');
       }
       for (const goal of body) {
+        // A statement checks this as it runs; a program built from its
+        // clauses directly is checked here, so no search meets a number.
+        if (!isCallable(goal) && !(goal instanceof Var)) {
+          throw new EyemindError(`line ${source.line}: a goal must be an atom, a compound term or a variable, not a number`);
+        }
         if (!stratifying && mayNeedStratifying(goal)) stratifying = true;
       }
       let headKey = null;

package/src/proof.js

@@ -116,10 +116,11 @@ function bindingsText(bindings, lettering) {
   return `{${parts.join(', ')}}`;
 }
 
-// The proof document of a run's claims and their derivations. With
-// checkable, also what checkRendered() needs to check it without reading the
-// document back: the document and that, as a pair.
-export function renderProof(program, claims, roots, checkable = false) {
+// The proof document of a run's claims and their derivations, opened by
+// heading, the comment that says what the claims are. With checkable, also
+// what checkRendered() needs to check it without reading the document back:
+// the document and that, as a pair. Comments are ignored when it is read.
+export function renderProof(program, claims, roots, checkable = false, heading = null) {
   const spellings = new Spellings();
   const steps = new Map();
   const cited = new Set();
@@ -135,12 +136,18 @@ export function renderProof(program, claims, roots, checkable = false) {
   // Variables are named A, B, ... in the order the document first shows
   // them, the claims written first, as in the run's conclusions.
   const lettering = new Lettering();
-  const lines = claims.map((claim) => spellings.lettered(claim, lettering));
+  const lines = heading === null ? [] : [heading];
+  for (const claim of claims) lines.push(spellings.lettered(claim, lettering));
   lines.push('');
+  if (cited.size) lines.push('// Clauses: the program clauses the steps cite, by clause number.');
   for (const clauseId of [...cited].sort((a, b) => a - b)) {
     lines.push(text(new Struct('clause', [BigInt(clauseId), clauseDisplay(program.byId.get(clauseId))])));
   }
   lines.push('');
+  if (steps.size) {
+    lines.push('// Steps: each goal, what justifies it (a clause, a builtin, a control, or an',
+      '// absence or collection taken on trust), the bindings and the goals it uses.');
+  }
   for (const node of steps.values()) {
     const uses = `[${node.children.map((child) => spellings.lettered(child.goal, lettering)).join(', ')}]`;
     lines.push(`step(${spellings.lettered(node.goal, lettering)}, ${text(node.by)}, ` +
@@ -499,7 +506,7 @@ function checkWitnesses(clause, head, names, env) {
   let firing = null;
   for (const name of witnessed) {
     const value = copyResolved(names.get(name), env);
-    if (!isTerm(value, 'skolem', 3) || value.args[0] !== BigInt(clause.id) || !witnessName(value.args[1], name)) return false;
+    if (!isTerm(value, 'skolem', 3) || value.args[0] !== BigInt(clause.id) || value.args[1] !== name) return false;
     if (firing === null) firing = value.args[2];
     else if (text(value.args[2]) !== text(firing)) return false;
   }
@@ -526,13 +533,6 @@ function checkWitnesses(clause, head, names, env) {
   return text(listFromItems(expected)) === text(firing);
 }
 
-// The name a witness of variable name carries: the name itself, or with a
-// number when a value of the firing brought in a variable of the same name.
-function witnessName(written, name) {
-  if (typeof written !== 'string' || !written.startsWith(name)) return false;
-  return written === name || /^[0-9]+$/.test(written.slice(name.length));
-}
-
 // C6: a trusted boundary cannot be proved, but evidence at hand can refute
 // it. An absence fails when a source fact, a step of this certificate or a
 // recomputed primitive is a solution; a collection fails when such a solution
@@ -552,7 +552,9 @@ function checkBoundaries(program, steps, boundaries, fail) {
   const nextSerial = () => ++serial;
 
   // Each solution of a simple goal that the evidence shows, or null when the
-  // evidence cannot speak for the goal.
+  // evidence cannot speak for the goal. A recomputed primitive always speaks,
+  // even when it fails; a predicate with no fact or step at all does not, so
+  // a boundary over it is left undecided rather than counted as confronted.
   function evidence(goal) {
     if (!isCallable(goal)) return null;
     const goalKey = key(goal);
@@ -567,13 +569,16 @@ function checkBoundaries(program, steps, boundaries, fail) {
       return [];
     }
     if (CONTROL_KEYS.has(goalKey)) return null;
+    let shown;
     if (INSPECTION_KEYS.has(goalKey)) {
-      return program.inspections.get(goalKey).map((entry) => freshTerm(entry.term, `evidence${nextSerial()}`));
+      shown = program.inspections.get(goalKey).map((entry) => freshTerm(entry.term, `evidence${nextSerial()}`));
+    } else {
+      const facts = (program.groups.get(goalKey) || [])
+        .filter((clause) => !clause.body.length && !clause.forward)
+        .map((clause) => freshTerm(clause.head, `evidence${nextSerial()}`));
+      shown = [...facts, ...(stepGoals.get(goalKey) || []).map((item) => freshTerm(item, `evidence${nextSerial()}`))];
     }
-    const facts = (program.groups.get(goalKey) || [])
-      .filter((clause) => !clause.body.length && !clause.forward)
-      .map((clause) => freshTerm(clause.head, `evidence${nextSerial()}`));
-    return [...facts, ...(stepGoals.get(goalKey) || []).map((item) => freshTerm(item, `evidence${nextSerial()}`))];
+    return shown.length ? shown : null;
   }
 
   for (const boundary of boundaries) {

package/src/version.js

@@ -1,2 +1,2 @@
 // The release this checkout is; ./release keeps it in step with package.json.
-export const VERSION = '0.1.30';
+export const VERSION = '0.1.32';