eyemind 0.1.26 → 0.1.28

package/README.md

@@ -16,9 +16,9 @@ JavaScript library, and a browser application, with no dependencies.
 - **[Specification](https://eyereasoner.github.io/eyemind/SPEC)**: the
   language, its canonical text, the proof format, and the C1–C8 checks.
 - **[Examples](https://eyereasoner.github.io/eyemind/examples/)**:
-  93 runnable programs, each with a card deck and saved conclusions, proofs
+  94 runnable programs, each with a card deck and saved conclusions, proofs
   and check reports.
-- **[Conformance suite](conformance/)**: 372 cases that test any
+- **[Conformance suite](conformance/)**: 384 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.26
+Version:    eyemind 0.1.28
 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.26, for readers who want
+the language and formats as implemented by eyemind 0.1.28, 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.
@@ -166,7 +166,14 @@ A premise is a goal or an array of goals, their conjunction (Section 5.1). A
 body goal that is a conjunction is split into its conjuncts; the clause body
 is the resulting sequence of goals.
 
-Clauses are numbered from 1 in the order they are stated. Each clause records
+`implies` and `implied_by` take exactly two arguments. Each call also returns
+a rule value; when that value is embedded in another statement of the same
+program build, the call contributes a template instead of a standalone clause
+(Section 4.6). An ignored or unembedded return value keeps its standalone
+clause.
+
+Clauses are numbered from 1 in the order they are stated, omitting embedded
+rule calls. Each clause records
 the line of the program on which the statement stating it begins; the facts
 of `facts_from` record the line of that call.
 
@@ -262,13 +269,29 @@ name MAY have different ranks.
 
 ### 4.6 Inline rule templates
 
-`forward(Body, Head)` and `backward(Head, Body)` construct rule templates.
-They MUST occur as top-level conjuncts of an `implies` conclusion. The
+Nested `implies(Body, Head)` and `implied_by(Head, Body)` calls construct rule
+templates. A rule value in a conclusion MUST occur as a top-level conjunct of
+an `implies` conclusion; in a body, `implies` and `implied_by` are inspection
+goals (Section 4.7). The
 conclusion MAY combine ordinary heads and several templates. Each template's
 body and head MAY themselves be conjunctions, written as arrays. A backward
 template with several heads defines one backward clause per head, sharing
 the same activation and body. Empty and open lists are not goals or heads.
 
+JavaScript evaluates inner calls first. When a statement embeds the rule
+value returned by an earlier call in the same program build, the earlier
+call's standalone registration MUST be removed before clause numbering and
+validation. This applies through arrays, helpers and stored values. A value
+MAY be reused in several generators; none of those uses restores its
+standalone registration. Separate program builds collect their registrations
+independently, even when a rule value is passed between them. Anonymous
+variables are named within each enclosing clause, so anonymous variables of
+the template cannot capture unrelated anonymous variables of the generator.
+
+The pure constructors `forward(Body, Head)` and `backward(Head, Body)` also
+construct templates with the same lowering and scope. They do not themselves
+register clauses.
+
 A template variable is **captured** when it also occurs in the generating
 clause's body or in an ordinary sibling head. The other variables are local
 to that template: they are universally quantified within the generated rule,
@@ -293,7 +316,7 @@ are numbered consecutively after them and inherit the generator's source line.
 Capture metadata belongs to each appended clause, including one whose head
 is subsequently lowered again.
 
-For example, `implies(cat(X), forward(dog(Y), test('yes')))` as the only
+For example, `implies(cat(X), implies(dog(Y), test('yes')))` as the only
 stated clause becomes these two clauses:
 
 ```js
@@ -309,8 +332,44 @@ activation dependencies participate in Section 4.5, including clauses whose
 generators never fire. A closed dependency cycle MUST therefore be rejected
 even if its template would remain inactive.
 
+### 4.7 Source rule inspection
+
+As goals, `implies(Body, Head)` and `implied_by(Head, Body)` match ordinary
+forward and backward source rules respectively. The fixed catalogue contains
+only original `implies` and `implied_by` clauses whose heads contain no rule
+templates and whose bodies contain no inspection goals, including inside
+controls. Facts, queries, contradictions, template generators and appended
+clauses are excluded. Inspecting rules therefore cannot inspect themselves.
+A rule value used as an inspection pattern is embedded in the inspecting
+statement (Section 4.6), so a stored rule value used as a pattern loses its
+standalone clause and is not in the catalogue.
+
+The catalogue keeps source order. A rule's body and forward head conjunctions
+are terms `and(...)`, as normalized goals are, and inspection arguments are
+goal positions. Each attempt freshens the whole rule with one variable map:
+shared variables stay shared, and different attempts are independent. Matching
+can instantiate these variables. Inspection reads the rule's structure; it
+does not solve its body or establish that its head holds.
+
+Free variables supplied by a successful inspection are scoped universal
+pattern variables. Forward conclusions preserve them, including through
+backward derivations and copied collection results. Derived patterns are
+identified up to variable renaming and freshened, together with their evidence,
+at every use. Unrelated unbound variables keep Section 7.2's witness behavior.
+When inspection variables remain free in a conclusion or its captured
+template context, that firing MUST NOT introduce head-only existential
+witnesses: it MUST fail with an error requiring the inspection variables to
+be bound first. Section 11.9 rejects certificates that bypass this boundary.
+
+Inspection uses a fixed source catalogue, so its own results do not depend on
+forward rounds. Other goals using derived patterns still participate in
+stratification. Negation and collection retain their explicit obligations.
+
 ## 5. Goals, Controls and Primitives
 
+The program-dependent source inspection goals `implies/2` and `implied_by/2`
+are defined in Section 4.7.
+
 ### 5.1 Controls
 
 | Control | Term | Meaning |
@@ -455,7 +514,8 @@ concluded:
   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
-  not terminate (Section 7.3). Derived facts are therefore ground. A
+  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);
 - a head `'true'` reports the instance of the rule's body, as a conjunction,
   once per distinct instance (by identity of canonical text);
@@ -473,6 +533,12 @@ witnesses of different captured contexts even when a head does not mention
 those values. An empty capture list still contributes one element, `[]`.
 Original clauses, including generators, use the ordinary witness convention.
 
+Scoped inspection variables of Section 4.7 are preserved instead of receiving
+witnesses; derived conclusions may therefore be universal patterns. Each use
+renames a pattern and its evidence apart. Such patterns are suppressed when
+an alpha-equivalent pattern was already derived. Other derived facts keep
+their ordinary ground identity convention.
+
 ### 7.3 Bounds
 
 A run is bounded by `max_depth`, the depth of nested rule bodies (default
@@ -658,6 +724,7 @@ order. `By` is one of:
 | `By` | Meaning | `Bindings` | `Uses` |
 | --- | --- | --- | --- |
 | `clause(N)` | `Goal` is an instance of a head of clause `N`, a fact or a rule, whose body instance is `Uses`. | the clause's variables | the body instance, empty for a fact |
+| `source(N)` | `Goal` is an instance of the inspectable source rule `N` as `implies(Body, Head)` or `implied_by(Head, Body)`. | empty | empty |
 | `'builtin'` | `Goal` is a primitive that holds. | empty | empty |
 | `'control'` | `Goal` is `call`, `once` or a disjunction, solved by `Uses`. | empty | the solved goals |
 | `'absent'` | `Goal` is a negation taken on trust. | empty | empty |
@@ -700,6 +767,14 @@ that afterwards the head is identical to `Goal` and each body goal to its
 use. A step's own terms MUST NOT need further instantiation to match: a
 source clause `same(X, X)` cannot justify `same('a', 'b')`.
 
+For a `source(N)` step, `N` MUST identify an eligible source rule of Section
+4.7. Bindings and uses MUST both be empty. The rule's inspection term,
+freshened with one variable map, MUST unify with `Goal` and resolve exactly
+to it without instantiating the step's own terms. This checks variable
+sharing as well as the rule's direction and structure. The source rule is
+read as data; its body is not derived by the checker. These steps count as
+verified C1 steps and cite the usual source clause display.
+
 ### 11.3 C2 Well-foundedness
 
 No step MAY depend on itself through the uses of steps.
@@ -768,6 +843,10 @@ bound to `skolem(N, Name, Args)`, where:
   the heads, that are ground and contain no Skolem term `skolem(N, _, Args)`:
   the values that do contain one hold a witness of this firing.
 
+When a forward clause has any such variables, its full head under the step's
+substitution MUST be ground. A generic inspection pattern cannot share one
+existential witness across all its instances (Section 4.7).
+
 For an appended forward clause of Section 4.6, prepend the capture list,
 instantiated under the step's substitution, as one element of `Args`, as
 required by Section 7.2. The checker MUST compute this from the source
@@ -782,7 +861,7 @@ covered by C8.
 
 | Condition | Covered |
 | --- | --- |
-| C1 resolution | `clause` steps that passed C1 |
+| C1 resolution | `clause` and `source` steps that passed C1 |
 | C2 well_founded | steps |
 | C3 justification | steps |
 | C4 coverage | claims plus uses |
@@ -792,7 +871,8 @@ covered by C8.
 | C8 witness_integrity | `clause` steps of forward rules with witnesses that passed C8 |
 
 A check also counts the **steps** it read, the **claims**, the `clause` steps
-**verified** by C1, the `'builtin'` steps **recomputed** by C5, the
+**verified** by C1, the `source` inspection steps also **verified** by C1,
+the `'builtin'` steps **recomputed** by C5, the
 `'control'` steps **composed** by C5, and the `'absent'` and `'collected'`
 steps **trusted**.
 
@@ -846,7 +926,7 @@ it differently. eyemind's details are, by condition:
 
 | Condition | Details |
 | --- | --- |
-| C1 | `clause display differs from source`, `unknown clause ...`, `not an instance of source clause N: ...` |
+| C1 | `clause display differs from source`, `unknown clause ...`, `not an instance of source clause N: ...`, `not an instance of inspectable source rule N: ...` |
 | C2 | `cyclic derivation at ...` |
 | C3 | the reader's error, `step bindings must be an object and uses an array`, `duplicate justification for ...`, `invalid builtin justification`, `trusted boundaries cannot have bindings or uses`, `unknown justification ...` |
 | C4 | `unjustified claim ...`, `unjustified use ...` |
@@ -957,7 +1037,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.26, byte for byte,
+conclusions, proof documents and reports as eyemind 0.1.28, 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,

package/package.json

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

package/src/engine.js

@@ -2,15 +2,16 @@
 import { PRIMITIVE_KEYS, primitive } from './builtins.js';
 import { freshClause, matchHead, renaming, text, variant } from './common.js';
 import { readGoal } from './goals.js';
+import { INSPECTION_KEYS } from './inspection.js';
 import { checkRendered, clauseDisplay, renderProof } from './proof.js';
 import { CONTROL_KEYS, Program } from './program.js';
 import { isActivation } from './templates.js';
 import {
   Env, EyemindError, Struct, Var, conjunction, copyResolved, deref, flattenConjunction, freshTerm,
-  identity, isCallable, isGround, isGroundButAnonymous, isTerm, key, keyArity, listFromItems, unify,
-  variables,
+  identity, isAnonymous, isCallable, isGround, isGroundButAnonymous, isTerm, key, keyArity, listFromItems,
+  unify, variables,
 } from './terms.js';
-import { Lettering, write } from './writer.js';
+import { Lettering, SourceNaming, write } from './writer.js';
 
 export const BUILTIN = 'builtin';
 export const CONTROL = 'control';
@@ -19,7 +20,7 @@ export const COLLECTED = 'collected';
 
 // One proof step: a goal, how it was justified, and the steps it used.
 export class Node {
-  constructor(goal, by, bindings = NO_NODES, children = NO_NODES, collectedUses = null, final = false) {
+  constructor(goal, by, bindings = NO_NODES, children = NO_NODES, collectedUses = null, final = false, scoped = NO_NODES) {
     this.goal = goal;
     // A derived fact's node is resolved once and for all when the fact is
     // derived, so whatever uses the fact shares the node, derivation and all.
@@ -30,6 +31,8 @@ export class Node {
     // A collection has no children in a proof, so its node keeps the clauses
     // its answers used.
     this.collectedUses = collectedUses;
+    this.scoped = scoped;
+    this.generic = false;
   }
 }
 
@@ -92,7 +95,7 @@ class Point {
   }
 
   count() {
-    if (this.kind === 'branch') return this.alternatives.length;
+    if (this.kind === 'branch' || this.kind === 'inspection') return this.alternatives.length;
     return this.stop - this.start + this.clauses.length;
   }
 }
@@ -104,7 +107,62 @@ const SPLICE = 'splice';
 function resolveOne(node, env) {
   return new Node(copyResolved(node.goal, env), node.by,
     node.bindings.map(([name, value]) => [name, copyResolved(value, env)]),
-    new Array(node.children.length).fill(null), node.collectedUses);
+    new Array(node.children.length).fill(null), node.collectedUses, false,
+    node.scoped.map((term) => copyResolved(term, env)));
+}
+
+// An inspected source rule supplies universal variables. Follow the recorded
+// evidence so ordinary fresh variables still receive existential witnesses.
+function scopedVariables(nodes, env) {
+  const found = new Map();
+  const seen = new Set();
+  const pending = [...nodes];
+  while (pending.length) {
+    const node = pending.pop();
+    if (seen.has(node)) continue;
+    seen.add(node);
+    if (isTerm(node.by, 'source', 1)) variables(copyResolved(node.goal, env), found);
+    for (const term of node.scoped) variables(copyResolved(term, env), found);
+    pending.push(...node.children);
+  }
+  return found;
+}
+
+// A universal derived pattern is renamed together with its evidence at each
+// use. Renaming just its head would disconnect the certificate's variables.
+function freshNode(node, suffix) {
+  const names = new Map();
+  const copies = new Map();
+  const make = (source) => new Node(freshTerm(source.goal, suffix, names, true), source.by,
+    source.bindings.map(([name, value]) => [name, freshTerm(value, suffix, names, true)]),
+    [], source.collectedUses, false, source.scoped.map((term) => freshTerm(term, suffix, names, true)));
+  const root = make(node);
+  copies.set(node, root);
+  const pending = [node];
+  while (pending.length) {
+    const source = pending.pop();
+    const target = copies.get(source);
+    for (const child of source.children) {
+      if (!copies.has(child)) {
+        copies.set(child, make(child));
+        pending.push(child);
+      }
+      target.children.push(copies.get(child));
+    }
+  }
+  return root;
+}
+
+// The error for a negation whose goal still has a variable to bind, naming
+// the variables as the program wrote them rather than as renamed apart.
+function unboundNegation(goal, env) {
+  const naming = new SourceNaming();
+  const resolved = copyResolved(goal, env);
+  const shown = write(resolved, null, naming);
+  const unbound = [...new Set([...variables(resolved).values()]
+    .filter((variable) => !isAnonymous(variable)).map((variable) => naming.get(variable.name)))];
+  return new EyemindError('negation requires a goal whose variables are bound, except for anonymous ones: ' +
+    `${unbound.join(', ')} ${unbound.length === 1 ? 'is' : 'are'} unbound in ${shown}`);
 }
 
 // Resolve a proof forest with an explicit stack: a derivation chain is as deep
@@ -189,7 +247,8 @@ export function clausesBehindBoundaries(program, roots) {
     const goalKey = pending.pop();
     if (seen.has(goalKey)) continue;
     seen.add(goalKey);
-    for (const clause of byKey.get(goalKey) || []) {
+    const candidates = INSPECTION_KEYS.has(goalKey) ? program.inspections.get(goalKey) : byKey.get(goalKey) || [];
+    for (const clause of candidates) {
       reached.add(clause.id);
       for (const goal of clause.body) visit(goal);
     }
@@ -213,7 +272,7 @@ export class Solver {
   constructor(program, options) {
     this.program = program;
     this.options = options;
-    this.recording = Boolean(options.proof);
+    this.recording = Boolean(options.proof || program.inspectionEnabled);
     this.serial = 0;
     this.facts = new Map();
     // Derived facts indexed by argument: for each name and arity, one map
@@ -221,6 +280,8 @@ export class Solver {
     // of the facts with that value there.
     this.factIndex = new Map();
     this.factKeys = new Set(program.groundFactKeys);
+    this.genericKeys = new Set();
+    this.genericPredicates = new Set();
     this.derived = [];
     this.reported = new Map();
     this.stats = { inferences: 0, rounds: 0, derived: 0 };
@@ -346,10 +407,7 @@ export class Solver {
     if (goalKey === 'not/1') {
       // Negation is a test, not a way to bind its variables; its anonymous
       // variables stand for any value.
-      if (!isGroundButAnonymous(goal.args[0], env)) {
-        throw new EyemindError('negation requires a goal whose variables are bound, ' +
-                              `except for anonymous ones: ${text(goal, env)}`);
-      }
+      if (!isGroundButAnonymous(goal.args[0], env)) throw unboundNegation(goal, env);
       const mark = env.mark();
       const iterator = this.solve([goal.args[0]], env, frame.depth + 1);
       let absent;
@@ -364,11 +422,18 @@ export class Solver {
     }
     if (goalKey === 'findall/3') {
       const items = [];
+      const scoped = [];
       const uses = recording ? new Set() : null;
       const mark = env.mark();
       for (const [answerEnv, nodes] of this.solve([goal.args[1]], env, frame.depth + 1)) {
         this.serial++;
-        items.push(freshTerm(copyResolved(goal.args[0], answerEnv), `collection${this.serial}`));
+        const names = new Map();
+        items.push(freshTerm(copyResolved(goal.args[0], answerEnv), `collection${this.serial}`, names));
+        if (this.program.inspectionEnabled && names.size) {
+          for (const name of scopedVariables(nodes, answerEnv).keys()) {
+            if (names.has(name)) scoped.push(names.get(name));
+          }
+        }
         if (recording) clausesUsed(nodes, uses);
       }
       env.undo(mark);
@@ -377,10 +442,12 @@ export class Solver {
         return null;
       }
       if (!recording) return this.advance(frame, null);
-      return this.advance(frame, new Node(goal, COLLECTED, NO_NODES, NO_NODES, uses));
+      return this.advance(frame, new Node(goal, COLLECTED, NO_NODES, NO_NODES, uses, false, scoped));
     }
     let point;
-    if (goalKey === 'or/2') {
+    if (INSPECTION_KEYS.has(goalKey)) {
+      point = new Point('inspection', frame, env.mark(), goal, { alternatives: this.program.inspections.get(goalKey) });
+    } else if (goalKey === 'or/2') {
       point = new Point('branch', frame, env.mark(), goal, { alternatives: goal.args });
     } else if (goalKey === 'call/1' || goalKey === 'once/1') {
       const cut = goalKey === 'once/1' ? choices.length : null;
@@ -410,6 +477,7 @@ export class Solver {
   }
 
   addFact(goalKey, node) {
+    if (node.generic) this.genericPredicates.add(goalKey);
     let facts = this.facts.get(goalKey);
     if (facts === undefined) {
       facts = [];
@@ -437,6 +505,7 @@ export class Solver {
   // The indexes of the derived facts a goal could match, in order, when an
   // argument of the goal narrows them down; null to try them all.
   factOrder(goal, env, goalKey) {
+    if (this.genericPredicates.has(goalKey)) return null;
     const positions = this.factIndex.get(goalKey);
     if (positions === undefined) return null;
     let best = null;
@@ -477,11 +546,21 @@ export class Solver {
         return this.childFrame(point.frame, [point.alternatives[position]],
           this.controlPending(point.goal, null), point.frame.depth + 1);
       }
+      if (point.kind === 'inspection') {
+        const source = point.alternatives[position];
+        this.serial++;
+        if (unify(point.goal, freshTerm(source.term, this.serial, new Map(), true), env)) {
+          return this.advance(point.frame, recording ? new Node(point.goal, new Struct('source', [BigInt(source.id)])) : null);
+        }
+        env.undo(point.mark);
+        continue;
+      }
       const inWindow = point.stop - point.start;
       if (position < inWindow) {
         let index = point.start + position;
         if (point.order !== null) index = point.order[index];
-        const fact = point.facts[index];
+        let fact = point.facts[index];
+        if (fact.generic) fact = freshNode(fact, ++this.serial);
         if (unify(point.goal, fact.goal, env)) {
           if (windowed) this.chosen[point.frame.index] = [0, index];
           return this.advance(point.frame, fact);
@@ -542,7 +621,7 @@ export class Solver {
         break;
       }
       const goalKey = key(goal);
-      if (PRIMITIVE_KEYS.has(goalKey) || goalKey === 'not/1' || goalKey === 'findall/3') {
+      if (PRIMITIVE_KEYS.has(goalKey) || INSPECTION_KEYS.has(goalKey) || goalKey === 'not/1' || goalKey === 'findall/3') {
         keys.push(null);
       } else if (CONTROL_KEYS.has(goalKey) || (this.program.groups.get(goalKey) || []).some((item) => item.body.length)) {
         keys = null;
@@ -630,11 +709,27 @@ export class Solver {
       // between the heads of one conclusion.
       const resolved = copyResolved(head, answerEnv);
       const unresolved = variables(resolved);
+      const captured = clause.captures === null ? null : copyResolved(body[0].args[1], answerEnv);
+      const relevant = this.program.inspectionEnabled
+        ? [...unresolved.keys(), ...(captured === null ? [] : variables(captured).keys())]
+        : [];
+      // Walking the evidence is linear in its size, so do it only when the
+      // conclusion or captures still have variables an inspection could scope.
+      if (relevant.length) {
+        const scoped = scopedVariables(nodes, answerEnv);
+        if (relevant.some((name) => scoped.has(name))) {
+          const inBody = new Set();
+          for (const goal of clause.body) for (const name of variables(goal).keys()) inBody.add(name);
+          if ([...variables(clause.head).keys()].some((name) => !inBody.has(name))) {
+            throw new EyemindError('bind inspected rule variables before deriving existential witnesses');
+          }
+        }
+        for (const name of scoped.keys()) unresolved.delete(name);
+      }
       if (unresolved.size) {
         // A generated rule also depends on its captures when its head omits
         // them; otherwise two enabled instances could share a witness.
-        const context = clause.captures === null ? null : copyResolved(body[0].args[1], answerEnv);
-        const witnesses = skolemTerms(clause, head, unresolved, answerEnv, context);
+        const witnesses = skolemTerms(clause, head, unresolved, answerEnv, captured);
         [...unresolved.values()].forEach((value, i) => unify(value, witnesses[i], answerEnv));
       }
       const conclusions = unresolved.size
@@ -678,7 +773,7 @@ export class Solver {
           for (const [conclusions, children, bindings, claim] of this.activations(clause)) {
             for (const conclusion of conclusions) {
               if (conclusion === 'true') {
-                const claimId = text(claim);
+                const claimId = this.program.inspectionEnabled ? variant(claim) : text(claim);
                 if (!this.reported.has(claimId)) this.reported.set(claimId, [claim, children, clause.id]);
                 continue;
               }
@@ -688,9 +783,11 @@ export class Solver {
                 this.haltCode = 65;
                 return;
               }
-              const conclusionId = identity(conclusion);
-              if (this.factKeys.has(conclusionId)) continue;
-              this.factKeys.add(conclusionId);
+              node.generic = this.program.inspectionEnabled && !isGround(conclusion);
+              const conclusionId = node.generic ? variant(conclusion) : identity(conclusion);
+              const factKeys = node.generic ? this.genericKeys : this.factKeys;
+              if (factKeys.has(conclusionId)) continue;
+              factKeys.add(conclusionId);
               this.addFact(key(conclusion), node);
               this.derived.push(node);
               this.stats.derived++;

package/src/goals.js

@@ -25,7 +25,7 @@ export function normalizeGoal(term) {
   if ((name === 'and' || name === 'or') && args.length === 2) {
     return rebuild(term, args.map(normalizeGoal));
   }
-  if ((name === 'forward' || name === 'backward') && args.length === 2) {
+  if (['implies', 'implied_by', 'forward', 'backward'].includes(name) && args.length === 2) {
     return rebuild(term, args.map(normalizeGoal));
   }
   if ((name === 'not' || name === 'call' || name === 'once') && args.length === 1) {

package/src/inspection.js

@@ -0,0 +1,17 @@
+// Rule inspection reads a fixed source catalogue, not the run's rule index.
+import { Struct, conjunction, isTerm } from './terms.js';
+
+export const INSPECTION_KEYS = new Set(['implies/2', 'implied_by/2']);
+export const isInspection = (term) => isTerm(term, 'implies', 2) || isTerm(term, 'implied_by', 2);
+
+export function hasInspection(goal) {
+  if (isInspection(goal)) return true;
+  if (isTerm(goal, 'and', 2) || isTerm(goal, 'or', 2)) return goal.args.some(hasInspection);
+  if (isTerm(goal, 'not', 1) || isTerm(goal, 'call', 1) || isTerm(goal, 'once', 1)) return hasInspection(goal.args[0]);
+  return isTerm(goal, 'findall', 3) && hasInspection(goal.args[1]);
+}
+
+export function inspectionTerm(clause) {
+  const body = conjunction(clause.body);
+  return new Struct(clause.forward ? 'implies' : 'implied_by', clause.forward ? [body, clause.head] : [clause.head, body]);
+}

package/src/lang.js

@@ -10,8 +10,9 @@
 // Atoms are strings, integers are numbers with an integral value or bigints,
 // floats are other numbers, lists are arrays, and [H, ...T] is a list with
 // head H and tail T. An array in a goal position is the conjunction of its
-// goals. Each call states one clause, in source order; loadText runs the
-// script and collects them into a Program.
+// goals. Rule calls embedded in another statement are templates; other
+// statements contribute clauses in source order. loadText runs the script
+// and collects them into a Program.
 //
 // A name the program does not define is supplied as it runs: a name
 // beginning with an uppercase letter or _ is the variable of that name, and
@@ -148,10 +149,13 @@ class Builder {
   constructor(locate) {
     this.sources = [];
     this.locate = locate;
+    this.rules = new WeakMap();
+    this.embedded = new Set();
   }
 
   add(kind, head, body, line = null) {
     if (line === null) line = statedLine !== null ? statedLine : this.locate();
+    const pending = [head, ...body];
     const counter = new Anonymous(head, body);
     // In the order the statement writes them: a forward rule, implies(),
     // writes its premise first.
@@ -171,7 +175,35 @@ class Builder {
       }
       if (goal === EMPTY) throw new EyemindError('an empty array is not a goal');
     }
-    this.sources.push(new Source(kind, head, body, line));
+    // JavaScript evaluates an inner rule first. Only a valid enclosing
+    // statement consumes it, using its value before anonymous renaming.
+    while (pending.length) {
+      const term = pending.pop();
+      if (!(term instanceof Struct)) continue;
+      const source = this.rules.get(term);
+      if (source !== undefined) this.embedded.add(source);
+      pending.push(...term.args);
+    }
+    const source = new Source(kind, head, body, line);
+    this.sources.push(source);
+    return source;
+  }
+
+  rule(name, args) {
+    if (args.length !== 2) throw new EyemindError(`${name} takes 2 arguments, got ${args.length}`);
+    const forward = name === 'implies';
+    const head = forward ? goalOf(args[1]) : toTerm(args[0]);
+    const premise = goalOf(args[forward ? 0 : 1]);
+    // Keep the returned value's anonymous variables untouched: each enclosing
+    // clause names its own occurrences, including those inside templates.
+    const value = new Struct(name, forward ? [premise, head] : [normalizeGoal(head), premise]);
+    const source = this.add(forward ? 'forward' : 'backward', head, [premise]);
+    this.rules.set(value, source);
+    return value;
+  }
+
+  program() {
+    return new Program(this.sources.filter((source) => !this.embedded.has(source)));
   }
 }
 
@@ -254,8 +286,8 @@ function exportsFor(io) {
     fact: (...terms) => {
       for (const term of terms) builder.add('fact', toTerm(term), []);
     },
-    implies: (premise, conclusion) => builder.add('forward', goalOf(conclusion), [goalOf(premise)]),
-    implied_by: (conclusion, premise) => builder.add('backward', toTerm(conclusion), [goalOf(premise)]),
+    implies: (...args) => active().rule('implies', args),
+    implied_by: (...args) => active().rule('implied_by', args),
     forward: (...args) => {
       if (args.length !== 2) throw new EyemindError(`forward takes 2 arguments, got ${args.length}`);
       return new Struct('forward', args.map(goalOf));
@@ -686,7 +718,7 @@ function execute(source, filename, builder, io) {
 export function loadText(source, filename = '<program>', io = null) {
   const builder = new Builder(() => null);
   execute(String(source).replace(/^#![^\n]*/, ''), filename, builder, io);
-  return new Program(builder.sources);
+  return builder.program();
 }
 
 // One Program from several sources, given as [text, filename] pairs, run in
@@ -696,7 +728,7 @@ export function loadSources(sources, io = null) {
   for (const [source, filename] of sources) {
     execute(String(source).replace(/^#![^\n]*/, ''), filename, builder, io);
   }
-  return new Program(builder.sources);
+  return builder.program();
 }
 
 // A Program from a function that states clauses when called: a function of a
@@ -706,7 +738,7 @@ export function build(statements) {
   const outer = builders.length ? builders[builders.length - 1] : null;
   const builder = new Builder(outer ? outer.locate : () => null);
   within(builder, () => statements(exportsFor(null)));
-  return new Program(builder.sources);
+  return builder.program();
 }
 
 export { FloatLiteral, PREDICATE };

package/src/program.js

@@ -1,13 +1,14 @@
 // A program: its clauses, validated, indexed and stratified.
 import { PRIMITIVE_KEYS } from './builtins.js';
-import { ACTIVATION_KEY, expandTemplates } from './templates.js';
+import { ACTIVATION_KEY, containsTemplate, expandTemplates } from './templates.js';
+import { hasInspection, inspectionTerm } from './inspection.js';
 import {
   Env, EyemindError, Struct, Var, deref, flattenConjunction, freshTerm, identity, isCallable,
   isGround, isTerm, key, keyArity, unify,
 } from './terms.js';
 
 export const CONTROL_KEYS = new Set(['and/2', 'or/2', 'not/1', 'call/1', 'once/1', 'findall/3']);
-export const RESERVED_KEYS = new Set(['step/4', 'clause/2', ACTIVATION_KEY, 'forward/2', 'backward/2']);
+export const RESERVED_KEYS = new Set(['step/4', 'clause/2', ACTIVATION_KEY, 'implies/2', 'implied_by/2', 'forward/2', 'backward/2']);
 
 // The statements that state a forward rule, and how an error names them.
 const FORWARD_KINDS = { forward: 'a forward rule', query: 'query()', contradiction: 'contradiction()' };
@@ -131,6 +132,8 @@ export class Program {
     // clauses: many groups of a large program are never asked for, and a
     // program made to leave one clause out is often run only briefly.
     this.indexes = new Map();
+    this.inspectionEnabled = this.clauses.some((clause) => clause.body.some(hasInspection));
+    this.inspectionCatalogue = null;
     // Ground source facts are compared against forward conclusions by
     // identity, so work those out once here.
     this.groundFactKeys = new Set();
@@ -140,6 +143,31 @@ export class Program {
     this.strata = stratify(this.clauses, stratifying);
   }
 
+  prepareInspections() {
+    if (this.inspectionCatalogue !== null) return;
+    this.inspectionCatalogue = new Map([['implies/2', []], ['implied_by/2', []]]);
+    this.inspectionSources = new Map();
+    for (const clause of this.clauses) {
+      const source = this.sources[clause.id - 1];
+      if (!source || !['forward', 'backward'].includes(source.kind) ||
+          containsTemplate(source.head) || source.body.some(hasInspection)) continue;
+      const term = inspectionTerm(clause);
+      const entry = { id: clause.id, term, body: [] };
+      this.inspectionCatalogue.get(key(term)).push(entry);
+      this.inspectionSources.set(clause.id, entry);
+    }
+  }
+
+  get inspections() {
+    this.prepareInspections();
+    return this.inspectionCatalogue;
+  }
+
+  get inspectedById() {
+    this.prepareInspections();
+    return this.inspectionSources;
+  }
+
   candidates(goal, env, goalKey) {
     const clauses = this.groups.get(goalKey);
     if (clauses === undefined) return [];

package/src/proof.js

@@ -11,6 +11,7 @@
 import { PRIMITIVE_KEYS, primitive } from './builtins.js';
 import { freshClause, text } from './common.js';
 import { readGoal } from './goals.js';
+import { INSPECTION_KEYS, isInspection } from './inspection.js';
 import { CONTROL_KEYS, Program } from './program.js';
 import { readTerms } from './reader.js';
 import { isActivation } from './templates.js';
@@ -320,6 +321,15 @@ function checkSteps(program, steps, allowTrusted, fail, spellings, name) {
     }
     if (isTerm(by, 'clause', 1)) {
       if (checkResolution(program, step, fail, tally)) tally.verified++;
+    } else if (isTerm(by, 'source', 1)) {
+      const clause = clauseNamed(program, by.args[0]);
+      const inspected = clause === null ? null : program.inspectedById.get(clause.id);
+      const env = new Env();
+      const pattern = inspected ? freshTerm(inspected.term, 'inspection') : null;
+      if (!inspected || bindings.length || uses.length || !isInspection(goal) ||
+          !unify(pattern, goal, env) || !resolvesTo(pattern, env, goal)) {
+        fail.add('C1', `not an instance of inspectable source rule ${text(by.args[0])}: ${text(goal)}`, goal);
+      } else tally.verified++;
     } else if (by === BUILTIN_BY) {
       if (bindings.length || uses.length || !isCallable(goal) || !PRIMITIVE_KEYS.has(key(goal))) {
         fail.add('C3', 'invalid builtin justification', goal);
@@ -493,6 +503,9 @@ function witnessNames(clause) {
 function checkWitnesses(clause, head, names, env) {
   const witnessed = witnessNames(clause);
   if (!witnessed.length) return null;
+  // An existential firing needs bound inspection values. A generic rule
+  // pattern cannot silently share one witness across all its instances.
+  if (!isGround(copyResolved(head, env))) return false;
   let firing = null;
   for (const name of witnessed) {
     const value = copyResolved(names.get(name), env);
@@ -564,6 +577,9 @@ function checkBoundaries(program, steps, boundaries, fail) {
       return [];
     }
     if (CONTROL_KEYS.has(goalKey)) return null;
+    if (INSPECTION_KEYS.has(goalKey)) {
+      return program.inspections.get(goalKey).map((entry) => freshTerm(entry.term, `evidence${nextSerial()}`));
+    }
     const facts = (program.groups.get(goalKey) || [])
       .filter((clause) => !clause.body.length && !clause.forward)
       .map((clause) => freshTerm(clause.head, `evidence${nextSerial()}`));

package/src/templates.js

@@ -1,15 +1,17 @@
 // Inline rule templates become statically visible clauses whose first
 // premise records the generating activation. No rule is installed at run time.
 import { normalizeGoal } from './goals.js';
+import { isInspection } from './inspection.js';
 import {
   EMPTY, EyemindError, Struct, Var, conjunction, flattenConjunction, isCallable, isTerm, listFromItems, variables,
 } from './terms.js';
 
 export const ACTIVATION_KEY = 'activated/2';
 export const isActivation = (term) => isTerm(term, 'activated', 2);
-const isTemplate = (term) => isTerm(term, 'forward', 2) || isTerm(term, 'backward', 2);
+const isTemplate = (term) => term instanceof Struct && term.args.length === 2 &&
+  ['implies', 'implied_by', 'forward', 'backward'].includes(term.name);
 
-function containsTemplate(term) {
+export function containsTemplate(term) {
   const pending = [term];
   while (pending.length) {
     const item = pending.pop();
@@ -19,31 +21,40 @@ function containsTemplate(term) {
   return false;
 }
 
-function checkGoal(goal, line) {
-  if (goal instanceof Var) throw new EyemindError(`line ${line}: generated rule bodies require statically named calls`);
-  if (!isCallable(goal) || goal === EMPTY || isTerm(goal, '.', 2)) {
+function checkGoal(goal, line, generated = false) {
+  if (generated && goal instanceof Var) throw new EyemindError(`line ${line}: generated rule bodies require statically named calls`);
+  if (generated && (!isCallable(goal) || goal === EMPTY || isTerm(goal, '.', 2))) {
     throw new EyemindError(`line ${line}: a generated rule goal must be an atom or a compound, not a number or list`);
   }
   if (!(goal instanceof Struct)) return;
+  if (isInspection(goal)) return;
   if (isTemplate(goal)) throw new EyemindError(`line ${line}: rule templates belong in an implies() conclusion`);
   if (isTerm(goal, 'and', 2) || isTerm(goal, 'or', 2)) {
-    for (const part of goal.args) checkGoal(part, line);
+    for (const part of goal.args) checkGoal(part, line, generated);
   } else if (['not', 'call', 'once'].includes(goal.name) && goal.args.length === 1) {
-    checkGoal(goal.args[0], line);
-  } else if (isTerm(goal, 'findall', 3)) checkGoal(goal.args[1], line);
+    checkGoal(goal.args[0], line, generated);
+  } else if (isTerm(goal, 'findall', 3)) {
+    if (containsTemplate(goal.args[0]) || containsTemplate(goal.args[2])) {
+      throw new EyemindError(`line ${line}: rule values in a body must be inspection goals`);
+    }
+    checkGoal(goal.args[1], line, generated);
+  } else if (containsTemplate(goal)) {
+    throw new EyemindError(`line ${line}: rule templates must be top-level conjuncts of an implies() conclusion or inspection goals`);
+  }
 }
 
 export function expandTemplates(sources) {
   const expanded = [...sources];
   for (let index = 0; index < expanded.length; index++) {
     const source = expanded[index];
+    for (const goal of source.body) checkGoal(goal, source.line, source.captures !== undefined);
     const heads = flattenConjunction(source.head);
     for (const head of heads) {
       if (isActivation(head)) throw new EyemindError(`line ${source.line}: activated/2 is reserved for generated rules`);
     }
     const templates = heads.filter(isTemplate);
     if (!templates.length) {
-      if (containsTemplate(source.head) || source.body.some(containsTemplate)) {
+      if (containsTemplate(source.head)) {
         throw new EyemindError(`line ${source.line}: rule templates must be top-level conjuncts of an implies() conclusion`);
       }
       continue;
@@ -51,9 +62,6 @@ export function expandTemplates(sources) {
     if (source.kind !== 'forward') {
       throw new EyemindError(`line ${source.line}: rule templates belong in an implies() conclusion`);
     }
-    if (source.body.some(containsTemplate)) {
-      throw new EyemindError(`line ${source.line}: rule templates belong in an implies() conclusion`);
-    }
     // Variables occurring outside a template are captured. Other variables
     // belong to that generated rule and are freshened by ordinary resolution.
     const outer = new Map();
@@ -64,7 +72,7 @@ export function expandTemplates(sources) {
         if (containsTemplate(head)) throw new EyemindError(`line ${source.line}: a rule template cannot be nested inside an ordinary term`);
         return head;
       }
-      const forward = head.name === 'forward';
+      const forward = head.name === 'implies' || head.name === 'forward';
       const premise = normalizeGoal(head.args[forward ? 0 : 1]);
       const conclusion = normalizeGoal(head.args[forward ? 1 : 0]);
       for (const item of flattenConjunction(conclusion)) {
@@ -73,7 +81,7 @@ export function expandTemplates(sources) {
         }
       }
       const body = flattenConjunction(premise);
-      for (const goal of body) checkGoal(goal, source.line);
+      for (const goal of body) checkGoal(goal, source.line, true);
       const captured = [...variables(head).values()].filter((variable) => outer.has(variable.name));
       const activation = new Struct('activated', [BigInt(expanded.length + 1), listFromItems(captured)]);
       const conclusions = forward ? [conclusion] : flattenConjunction(conclusion);

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.26';
+export const VERSION = '0.1.28';

package/src/writer.js

@@ -150,6 +150,34 @@ export class Lettering {
   }
 }
 
+// Names for write() that spell variables as the program wrote them, for
+// messages about a running goal: the renamed-apart X#12 is X again and each
+// anonymous variable is _. Distinct variables that share a name are numbered,
+// so a message never shows two of them as one.
+export class SourceNaming {
+  constructor() {
+    this.names = new Map();
+    this.taken = new Set();
+  }
+
+  get(name) {
+    let shown = this.names.get(name);
+    if (shown === undefined) {
+      const hash = name.indexOf('#');
+      const base = hash < 0 ? name : name.slice(0, hash);
+      if (/^_[0-9]*$/.test(base)) {
+        shown = '_';
+      } else {
+        shown = variableText(base);
+        for (let n = 2; this.taken.has(shown); n++) shown = variableText(`${base}_${n}`);
+        this.taken.add(shown);
+      }
+      this.names.set(name, shown);
+    }
+    return shown;
+  }
+}
+
 // Names for write() that name nothing but notice a variable.
 class Spy {
   constructor() {