eyemind 0.1.24 → 0.1.26

package/README.md

@@ -15,10 +15,10 @@ JavaScript library, and a browser application, with no dependencies.
   write rules, check proofs, use the library, and develop eyemind.
 - **[Specification](https://eyereasoner.github.io/eyemind/SPEC)**: the
   language, its canonical text, the proof format, and the C1–C8 checks.
-- **[Examples](examples/)**: 90 runnable programs, with their conclusions,
-  proofs and check reports, and a
-  [card deck](https://eyereasoner.github.io/eyemind/examples/deck/) for each.
-- **[Conformance suite](conformance/)**: 356 cases that test any
+- **[Examples](https://eyereasoner.github.io/eyemind/examples/)**:
+  93 runnable programs, each with a card deck and saved conclusions, proofs
+  and check reports.
+- **[Conformance suite](conformance/)**: 372 cases that test any
   implementation of the specification through its command line.
 
 ```js
@@ -30,6 +30,7 @@ query(type(X, Y))
 
 ```sh
 node bin/eyemind.js examples/socrates.js
+node bin/eyemind.js -c examples/socrates.js
 node bin/eyemind.js --proof examples/socrates.js > /tmp/proof.js
 node bin/eyemind.js --check-proof /tmp/proof.js examples/socrates.js
 ```

package/SPEC.md

@@ -2,7 +2,7 @@
 
 ```text
 Title:      The eyemind Rule Language and Proof Format
-Version:    eyemind 0.1.24
+Version:    eyemind 0.1.26
 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.24, for readers who want
+the language and formats as implemented by eyemind 0.1.26, 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.
@@ -145,7 +145,7 @@ loaded as one program; their clauses are then numbered in the order the
 scripts are run.
 
 A program is given exactly the names needed to state it: the statements of
-Section 4.2, `preds`, `vars`, `struct`, the controls and primitives of
+Section 4.2, `forward`, `backward`, `preds`, `vars`, `struct`, the controls and primitives of
 Section 5, the atom `fail`, and `eyemind`, the library, with which a program
 can build and run another program and read and write documents
 (`eyemind.build`, `eyemind.run`, `eyemind.checkProof`, `eyemind.checkReport`,
@@ -180,7 +180,8 @@ statements) would run as JavaScript code.
 A clause MUST be rejected when:
 
 - a head is not an atom or a compound;
-- a head is `step/4` or `clause/2`, which are reserved for proof documents;
+- a head is `step/4` or `clause/2`, which are reserved for proof documents,
+  or explicitly states `activated/2`, reserved for template activations;
 - a head is a primitive (Section 5.2) or a control (Section 5.1), except the
   head `'true'` of a query and `'false'` of a contradiction; in particular a
   conclusion of `implies` is never `'true'` or `'false'`;
@@ -230,7 +231,8 @@ Section 5.1 treats as anonymous.
 
 In a goal position, an array is the conjunction of its items: a statement's
 goal, the argument of `and`, `or`, `not`, `call` and `once`, and the goal of
-`findall`. Anywhere else an array is a list.
+`findall`, and either part of a rule template (Section 4.6). Anywhere else an
+array is a list.
 
 Operators do not build terms. Variables, compounds and predicates have no
 JavaScript primitive value, so an operator applied to one, such as `X + 1` or
@@ -258,6 +260,55 @@ A program MUST be rejected when:
 Because dependencies compare whole terms, two relations sharing a predicate
 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
+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.
+
+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,
+except for head-only variables of a forward template, which receive witnesses
+as Section 7.2 describes. Variables shared only between sibling templates are
+local to each. Every call in a template body, including calls inside controls,
+MUST be statically named; a variable in a term's argument is permitted, but a
+variable used as a goal is not. A forward template MAY conclude further inline
+templates. A backward template MUST NOT conclude templates.
+
+Templates are lowered before validation, indexing and stratification. Starting
+with all stated clauses, in clause order, replace each template conjunct,
+left to right, with `activated(N, Captures)`. `Captures` is a list of its
+captured variables in order of first occurrence in the template as written;
+`N` is the number of the first clause appended for it. Append a forward or
+backward clause as specified by the template, with the activation as its first
+body goal, followed by the template's body goals. A forward template keeps its
+head conjunction; a backward template appends one clause per head in order.
+Continue processing the appended clauses in order, lowering any nested
+templates the same way. Original clause numbers are kept; appended clauses
+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
+stated clause becomes these two clauses:
+
+```js
+implies(cat(X), activated(2, []))
+implies([activated(2, []), dog(Y)], test('yes'))
+```
+
+`Y` stays local to the second clause. Its activation is required even though
+the template does not capture `X`. A generator with several solutions but
+identical captures enables the same rule instance. No arbitrary rule term is
+installed during reasoning. All potential generated clauses and their
+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.
+
 ## 5. Goals, Controls and Primitives
 
 ### 5.1 Controls
@@ -416,6 +467,12 @@ concluded:
 When the run asks its own goals (Section 7.4), rules whose heads are all
 `'true'` are not run.
 
+For an appended forward clause of Section 4.6, prepend one element to
+`Arguments`: the grounded capture list of its activation. This distinguishes
+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.
+
 ### 7.3 Bounds
 
 A run is bounded by `max_depth`, the depth of nested rule bodies (default
@@ -442,12 +499,16 @@ A run that concluded `'false'` has halt code 65; otherwise it has none.
 
 The conclusions of a run are, in order:
 
-1. when it halted: every derived fact, in the order derived, ending with
+1. when it halted: every derived fact except template activations, in the order derived, ending with
    `'false'`;
 2. otherwise, when it was given goals: the reported instances of its goals;
 3. otherwise, when the program has a forward rule with a head `'true'`: the
    reported instances, in order of first report, which MAY be none;
-4. otherwise: every derived fact, in the order derived.
+4. otherwise: every derived fact except template activations, in the order derived.
+
+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.
@@ -575,6 +636,13 @@ array of its body goals when it has several, `Head` likewise the head or the
 array of heads, and `G1, ...` are the body goals themselves. Displays are not
 authority: a checker MUST compare each with the program it checks against.
 
+For a program with templates, displays show the deterministically lowered
+clauses of Section 4.6, including activation heads and premises. The program
+supplied to the checker MUST be lowered from the source as Section 4.6
+requires; displays cannot authorize extra generated rules. Each use of a
+generated clause requires its activation as the first use, with a justified
+step of its own. All existing checks apply.
+
 ### 10.3 Steps
 
 `Goal` is the justified goal as it stands once the whole solution is found:
@@ -679,7 +747,7 @@ A boundary that is not refuted remains an obligation (Section 12).
 
 When goals were given and no claim is `'false'`, the questions are the goals.
 Otherwise the questions are, for each forward rule, each head other than
-`'true'`, and the rule's body as a conjunction when one of its heads is
+`'true'` or a template activation, and the rule's body as a conjunction when one of its heads is
 `'true'` and no claim is `'false'`. Each claim MUST be an instance of a
 question. Each step MUST be reachable from a conjunct of a claim through the
 conjuncts of uses.
@@ -700,6 +768,11 @@ 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.
 
+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
+template's capture metadata and the substitution, not from the witness term.
+
 A variable of the head that also occurs in the body is not checked by C8,
 even when the body leaves it unbound; its value comes from the uses, which
 other conditions check. A step citing a rule without such variables is not
@@ -736,8 +809,9 @@ leave conclusions out, and a run's own proof holds exactly its conclusions.
 
 ## 12. Check Reports
 
-A check report is a document (Section 9) holding, in this order, one fact per
-line:
+A check report is a document (Section 9) beginning with the proof's claims,
+in proof order, in canonical text, one per line, followed by a blank line and
+the following report facts, one per line:
 
 1. `condition(Id, Name, Outcome, Covered)` for C1 to C8, where `Outcome` is
    `'ok'` or `failed(N)`, `N` the number of that condition's failures;
@@ -751,6 +825,15 @@ line:
    otherwise `'checked_with_obligations'` when there are obligations,
    otherwise `'checked'`.
 
+Comments MUST identify these initial terms as checked answers only when the
+report is valid with no obligations. A valid report with obligations MUST
+label them as conditional on those obligations. A failed report MUST label
+them as unverified claims; their inclusion does not validate them. A valid
+report with no claims MUST say it establishes no conclusions. Comments also
+explain the C1-C8 order, failures and obligations when present, the statistics,
+and that the verdict does not establish completeness. Comments are informative
+and MAY be worded differently. They are ignored when the document is read.
+
 Failures are listed in the order they are found: those of reading the
 document (Section 11.1), in document order; C4 for each claim, in claim
 order; then for each step, in document order, C4 for its uses and the C1, C3,
@@ -772,11 +855,13 @@ it differently. eyemind's details are, by condition:
 | C7 | `claim answers no goal: ...`, `step serves no claim: ...` |
 | C8 | `not the witness of this firing of clause N: ...` |
 
-The variables of each fact are renamed `A`, `B`, ..., `Z`, `A1`, ... in order
+The initial answers keep the variable names of the proof. The variables of
+each subsequent report fact are renamed `A`, `B`, ..., `Z`, `A1`, ... in order
 of first occurrence. A report is ordinary data: `facts_from` (Section 4.2)
 states it as facts.
 
-The JSON form of a report is an object with `valid` (boolean), `steps`,
+The JSON form includes `answers`, an array of the initial claims' canonical
+texts, including unverified claims when `valid` is false. It also has `valid` (boolean), `steps`,
 `claims`, `verified`, `redecided` (the count `recomputed`), `composed`,
 `uses` (the number of uses of all steps, integers), `trusted`
 (a list of `{kind, conclusion}`), `failures` (a list of
@@ -815,18 +900,22 @@ eyemind [OPTION ...] [FILE ...]
 | --- | --- |
 | (none) | Load the files, or standard input, as one program and print its conclusions. |
 | `-p`, `--proof` | Print the proof document instead. |
-| `-c FILE`, `--check-proof FILE` | Check the proof in `FILE` (`-` for standard input) against the program and print its report. |
-| `--json` | With `--check-proof`, print the report as JSON. |
+| `-c`, `--prove-and-check` | Generate a proof, check the rendered proof against the input program, and print its answers and check report. |
+| `--check-proof FILE` | Check the proof in `FILE` (`-` for standard input) against the program and print its answers and report. |
+| `--json` | With either checking mode, print the report, including `answers`, as JSON. |
 | `--goal GOAL` | Ask `GOAL`, read as in Section 9, where an array is a conjunction; MAY be repeated. With `--check-proof`, the goals the proof answers. |
-| `--strict-proof` | With `--check-proof`, forbid trusted boundaries. |
+| `--strict-proof` | With either checking mode, forbid trusted boundaries. |
 | `--unused` | Print the unused clauses (Section 13). |
 | `--stats` | Print reasoning statistics as JSON to standard error: `inferences`, the goals started, which `--max-inferences` bounds; `rounds`, the forward rounds run over all strata; and `derived`, the facts forward rules added, not counting a conclusion the program states as a fact, a query's answers or `'false'`. |
 | `--max-depth N`, `--max-iterations N`, `--max-inferences N` | The bounds of Section 7.3; `N` MUST be a positive safe integer, at most 9007199254740991. |
 | `-v`, `--version` | Print the version. |
 | `-h`, `--help` | Print the usage, including every option and its short alias where one exists. |
 
-`--check-proof` MUST NOT be combined with `--proof`, nor `--unused` with
-either, and `--json` and `--strict-proof` need `--check-proof`. A program
+`--proof`, `--prove-and-check`, `--check-proof` and `--unused` are mutually
+exclusive. `--json` and `--strict-proof` need a checking mode. With
+`--prove-and-check`, reasoning bounds and `--stats` apply to proof generation;
+an invalid check returns 2, otherwise the run's halt code is retained
+(65 for a contradiction, 0 otherwise). A program
 text that has a line starting with `step(` is a proof document; given one as
 a program, the command line MUST say how to check it instead.
 
@@ -868,8 +957,8 @@ 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.24, byte for byte,
-except for the `Detail` texts of failures (Section 12), the internal names of
+conclusions, proof documents and reports as eyemind 0.1.26, 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,
 `pow` of floats) differ in the last digit.
@@ -945,6 +1034,12 @@ step(subclass_of('human', 'mortal'), clause(2), {}, [])
 Its check report (Section 12):
 
 ```js
+// Checked answers: these follow from the input program.
+type('socrates', 'mortal')
+type('socrates', 'human')
+
+// C1-C8: resolution, acyclicity, justification, coverage,
+// re-decision, boundary consistency, relevance and witness integrity.
 condition('C1', 'resolution', 'ok', 3)
 condition('C2', 'well_founded', 'ok', 3)
 condition('C3', 'justification', 'ok', 3)
@@ -953,11 +1048,15 @@ condition('C5', 're_decision', 'ok', 0)
 condition('C6', 'boundary_consistency', 'ok', 0)
 condition('C7', 'relevance', 'ok', 5)
 condition('C8', 'witness_integrity', 'ok', 0)
+
+// Proof statistics: recorded steps and how they were checked.
 steps(3)
 verified(3)
 recomputed(0)
 composed(0)
 trusted(0)
 claims(2)
+
+// This verdict applies to the claims above; it does not establish completeness.
 verdict('checked')
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyemind",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "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

@@ -8,7 +8,8 @@ import { VERSION } from './version.js';
 export const HELP = `Usage: eyemind [OPTION ...] [FILE ...]
 Programs are JavaScript; forward rules run to a fixpoint.
   -p, --proof             Print the claims with clause(...) and step(...) records
-  -c, --check-proof FILE  Print a C1-C8 check report of a proof (- for stdin)
+  -c, --prove-and-check   Generate a proof and check it against the input program
+      --check-proof FILE  Print checked answers and a C1-C8 report (- for stdin)
       --json              Print the check report as JSON instead
       --goal GOAL         Ask a backward goal after forward reasoning; with
                           --check-proof, the goal the proof answers
@@ -46,6 +47,7 @@ export function main(argv, io) {
     let strictProof = false;
     let asJson = false;
     let unused = false;
+    let proveAndCheck = false;
     for (let i = 0; i < argv.length; i++) {
       const arg = argv[i];
       if (arg === '--help' || arg === '-h') {
@@ -58,6 +60,8 @@ export function main(argv, io) {
       }
       if (arg === '--proof' || arg === '-p') {
         options.proof = true;
+      } else if (arg === '--prove-and-check' || arg === '-c') {
+        proveAndCheck = true;
       } else if (arg === '--stats') {
         stats = true;
       } else if (arg === '--strict-proof') {
@@ -66,11 +70,11 @@ export function main(argv, io) {
         asJson = true;
       } else if (arg === '--unused') {
         unused = true;
-      } else if (arg === '--check-proof' || arg === '-c' || arg === '--goal' || Object.hasOwn(LIMITS, arg)) {
+      } else if (arg === '--check-proof' || arg === '--goal' || Object.hasOwn(LIMITS, arg)) {
         i++;
         if (i >= argv.length) throw new UsageError(`${arg} needs a value`);
         const value = argv[i];
-        if (arg === '--check-proof' || arg === '-c') {
+        if (arg === '--check-proof') {
           proofFile = value;
         } else if (arg === '--goal') {
           goals.push(value);
@@ -85,11 +89,14 @@ export function main(argv, io) {
         files.push(arg);
       }
     }
-    if (asJson && proofFile === null) throw new UsageError('--json requires --check-proof');
-    if (strictProof && proofFile === null) throw new UsageError('--strict-proof requires --check-proof');
+    if (asJson && proofFile === null && !proveAndCheck) throw new UsageError('--json requires --check-proof or --prove-and-check');
+    if (strictProof && proofFile === null && !proveAndCheck) throw new UsageError('--strict-proof requires --check-proof or --prove-and-check');
+    if (proveAndCheck && (proofFile !== null || options.proof)) {
+      throw new UsageError('--prove-and-check cannot be combined with --proof or --check-proof');
+    }
     if (proofFile !== null && options.proof) throw new UsageError('--check-proof cannot be combined with --proof');
-    if (unused && (proofFile !== null || options.proof)) {
-      throw new UsageError('--unused cannot be combined with --proof or --check-proof');
+    if (unused && (proofFile !== null || options.proof || proveAndCheck)) {
+      throw new UsageError('--unused cannot be combined with --proof, --check-proof or --prove-and-check');
     }
     if (proofFile === '-' && (!files.length || files.includes('-'))) {
       throw new UsageError('stdin holds the proof; name the program as files');
@@ -108,7 +115,15 @@ export function main(argv, io) {
       stdout(unusedClauses(program, { goals, ...options }));
       return 0;
     }
-    const result = run(program, { goals, ...options });
+    const result = run(program, { goals, ...options, proof: options.proof || proveAndCheck });
+    if (proveAndCheck) {
+      // Check the rendered certificate against the input, just as a saved
+      // proof is checked; no second reasoning run supplies missing evidence.
+      const report = checkProof(program, result.proof, { goals, allowTrusted: !strictProof });
+      stdout(asJson ? `${JSON.stringify(publicReport(report), null, 2)}\n` : checkReport(report));
+      if (stats) stderr(`${JSON.stringify(result.stats)}\n`);
+      return report.valid ? result.haltCode || 0 : 2;
+    }
     stdout(result.stdout);
     if (stats) stderr(`${JSON.stringify(result.stats)}\n`);
     return result.haltCode || 0;

package/src/engine.js

@@ -4,6 +4,7 @@ import { freshClause, matchHead, renaming, text, variant } from './common.js';
 import { readGoal } from './goals.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,
@@ -630,7 +631,10 @@ export class Solver {
       const resolved = copyResolved(head, answerEnv);
       const unresolved = variables(resolved);
       if (unresolved.size) {
-        const witnesses = skolemTerms(clause, head, unresolved, answerEnv);
+        // 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);
         [...unresolved.values()].forEach((value, i) => unify(value, witnesses[i], answerEnv));
       }
       const conclusions = unresolved.size
@@ -704,8 +708,8 @@ export class Solver {
 // variable and the values the solution gave the heads' other variables. The
 // same activation thus always gives the same terms, and a different one
 // different terms.
-export function skolemTerms(clause, head, unresolved, env) {
-  const values = [];
+export function skolemTerms(clause, head, unresolved, env, context = null) {
+  const values = context === null ? [] : [context];
   for (const variable of variables(head).values()) {
     const value = copyResolved(variable, env);
     if (isGround(value)) values.push(value);
@@ -741,7 +745,7 @@ export class Result {
 
   // The derived facts as text, written only when asked for.
   get inferred() {
-    return this.derived.map((node) => text(node.goal));
+    return this.derived.filter((node) => !isActivation(node.goal)).map((node) => text(node.goal));
   }
 }
 
@@ -808,6 +812,7 @@ function reason(program, goalInputs, options) {
     }
   } else {
     for (const node of solver.derived) {
+      if (isActivation(node.goal)) continue;
       roots.push(node);
       claims.push(node.goal);
     }

package/src/goals.js

@@ -2,12 +2,12 @@
 //
 // An array in a goal position is the conjunction of its items: [p(X), q(X)]
 // is and(p(X), q(X)). A goal position is a statement's goal, an argument of
-// and, or, not, call or once, or the goal of findall. Anywhere else an array
-// is a list.
-import { EMPTY, Struct, conjunction, properListItems } from './terms.js';
+// and, or, not, call or once, either part of a rule template, or the goal of
+// findall. Anywhere else an array is a list.
+import { EMPTY, Env, Struct, conjunction, properListItems } from './terms.js';
 import { readTerm } from './reader.js';
 
-const EMPTY_ENV = { bindings: new Map() };
+const EMPTY_ENV = new Env();
 
 function isList(term) {
   return term === EMPTY || (term instanceof Struct && term.name === '.' && term.args.length === 2);
@@ -25,6 +25,9 @@ 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) {
+    return rebuild(term, args.map(normalizeGoal));
+  }
   if ((name === 'not' || name === 'call' || name === 'once') && args.length === 1) {
     return rebuild(term, [normalizeGoal(args[0])]);
   }

package/src/lang.js

@@ -256,6 +256,14 @@ function exportsFor(io) {
     },
     implies: (premise, conclusion) => builder.add('forward', goalOf(conclusion), [goalOf(premise)]),
     implied_by: (conclusion, premise) => builder.add('backward', toTerm(conclusion), [goalOf(premise)]),
+    forward: (...args) => {
+      if (args.length !== 2) throw new EyemindError(`forward takes 2 arguments, got ${args.length}`);
+      return new Struct('forward', args.map(goalOf));
+    },
+    backward: (...args) => {
+      if (args.length !== 2) throw new EyemindError(`backward takes 2 arguments, got ${args.length}`);
+      return new Struct('backward', args.map(goalOf));
+    },
     query: (...body) => builder.add('query', TRUE_ATOM, body.map(goalOf)),
     contradiction: (...body) => builder.add('contradiction', 'false', body.map(goalOf)),
     facts_from: (source) => {

package/src/program.js

@@ -1,19 +1,20 @@
 // A program: its clauses, validated, indexed and stratified.
 import { PRIMITIVE_KEYS } from './builtins.js';
+import { ACTIVATION_KEY, expandTemplates } from './templates.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']);
+export const RESERVED_KEYS = new Set(['step/4', 'clause/2', ACTIVATION_KEY, '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()' };
 const isIndexable = (value) => typeof value === 'string' || typeof value === 'bigint' || typeof value === 'number';
 
 export class Clause {
-  constructor(id, head, heads, body, forward, line) {
+  constructor(id, head, heads, body, forward, line, captures = null) {
     this.id = id;
     this.head = head;
     // Only a forward rule can have several heads, so only it stores them.
@@ -21,6 +22,7 @@ export class Clause {
     this.body = body;
     this.forward = forward;
     this.line = line;
+    this.captures = captures;
     this.renaming = null; // how to rename it apart, worked out once it is used often
     this.uses = 0;
   }
@@ -68,6 +70,8 @@ function pushGoals(goal, out) {
 export class Program {
   constructor(sources, without = null) {
     this.sources = [...sources];
+    const expanded = expandTemplates(this.sources);
+    this.maxClauseId = expanded.length;
     this.clauses = [];
     this.byId = new Map();
     this.groups = new Map();
@@ -77,9 +81,9 @@ export class Program {
     // made once, and a key once allowed as a head is not checked again.
     const keys = new KeyCache();
     const allowed = new Set();
-    const count = this.sources.length;
+    const count = expanded.length;
     for (let index = 0; index < count; index++) {
-      const source = this.sources[index];
+      const source = expanded[index];
       const ordinal = index + 1;
       if (ordinal === without) continue;
       const forward = Object.hasOwn(FORWARD_KINDS, source.kind);
@@ -104,14 +108,14 @@ export class Program {
         const itemKey = keys.of(item);
         headKey = itemKey;
         if (allowed.has(itemKey)) continue;
-        if (RESERVED_KEYS.has(itemKey) ||
+        if ((RESERVED_KEYS.has(itemKey) && itemKey !== ACTIVATION_KEY) ||
             ((PRIMITIVE_KEYS.has(itemKey) || CONTROL_KEYS.has(itemKey)) &&
              !(forward && (item === 'true' || item === 'false')))) {
           throw new EyemindError(`line ${source.line}: unsupported or reserved head ${itemKey}`);
         }
         allowed.add(itemKey);
       }
-      const clause = new Clause(ordinal, source.head, forward ? heads : null, body, forward, source.line);
+      const clause = new Clause(ordinal, source.head, forward ? heads : null, body, forward, source.line, source.captures ?? null);
       this.clauses.push(clause);
       this.byId.set(ordinal, clause);
       if (forward) {

package/src/proof.js

@@ -13,6 +13,7 @@ import { freshClause, text } from './common.js';
 import { readGoal } from './goals.js';
 import { CONTROL_KEYS, Program } from './program.js';
 import { readTerms } from './reader.js';
+import { isActivation } from './templates.js';
 import {
   Env, EyemindError, Struct, Var, conjunction, copyResolved, deref, flattenConjunction, freshTerm,
   isCallable, isGround, isTerm, key, listFromItems, properListItems, unify, variables,
@@ -215,6 +216,7 @@ function check(program, claims, steps, goals, allowTrusted, fail, spellings, nam
     valid: !fail.items.length,
     steps: steps.size,
     claims: claims.length,
+    answers: claims.map((claim) => name(claim)),
     verified: tally.verified,
     redecided: tally.redecided,
     composed: tally.composed,
@@ -284,7 +286,7 @@ function readDocument(program, document, fail, spellings) {
 }
 
 function clauseNamed(program, id) {
-  if (typeof id !== 'bigint' || id < 1n || id > BigInt(program.sources.length)) return null;
+  if (typeof id !== 'bigint' || id < 1n || id > BigInt(program.maxClauseId)) return null;
   return program.byId.get(Number(id)) ?? null;
 }
 
@@ -509,7 +511,11 @@ function checkWitnesses(clause, head, names, env) {
     }
     return false;
   };
-  const expected = [];
+  // Recover captures from the source clause and substitution, independently
+  // of the proposed witness, including captures the head does not mention.
+  const expected = clause.captures === null ? [] : [listFromItems(
+    clause.captures.map((name) => copyResolved(names.get(name), env)),
+  )];
   for (const variable of variables(head).values()) {
     const value = copyResolved(variable, env);
     if (isGround(value) && !ofThisFiring(value)) expected.push(value);
@@ -625,7 +631,7 @@ function checkRelevance(program, claims, steps, goals, fail, spellings) {
       if (heads.some((head) => head === 'true')) {
         if (!halted && clause.body.length) questions.push(conjunction(clause.body));
       }
-      for (const head of heads) if (head !== 'true') questions.push(head);
+      for (const head of heads) if (head !== 'true' && !isActivation(head)) questions.push(head);
     }
   }
   for (const claim of claims) {
@@ -727,7 +733,27 @@ export function checkReport(report) {
     facts.push(new Struct(name, [BigInt(count)]));
   }
   facts.push(new Struct('verdict', [verdict(report)]));
-  return facts.map((fact) => `${text(lettered(fact))}\n`).join('');
+  const heading = !report.valid ? '// Unverified claims: proof checking failed.'
+    : !report.answers.length ? '// No answers claimed; this check establishes no conclusions.'
+    : report.trusted.length ? '// Answers checked subject to the obligations below.'
+    : '// Checked answers: these follow from the input program.';
+  const lines = [heading, ...report.answers, '',
+    '// C1-C8: resolution, acyclicity, justification, coverage,',
+    '// re-decision, boundary consistency, relevance and witness integrity.'];
+  let previous = null;
+  for (const fact of facts) {
+    if (fact.name === 'failure' && previous !== 'failure') {
+      lines.push('', '// Failures: the claims above have not passed every check.');
+    }
+    if (fact.name === 'obligation' && previous !== 'obligation') {
+      lines.push('', '// Obligations: absence and collection completeness are taken on trust.');
+    }
+    if (fact.name === 'steps') lines.push('', '// Proof statistics: recorded steps and how they were checked.');
+    if (fact.name === 'verdict') lines.push('', '// This verdict applies to the claims above; it does not establish completeness.');
+    lines.push(text(lettered(fact)));
+    previous = fact.name;
+  }
+  return `${lines.join('\n')}\n`;
 }
 
 export function verdictText(report) {

package/src/templates.js

@@ -0,0 +1,91 @@
+// 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 {
+  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);
+
+function containsTemplate(term) {
+  const pending = [term];
+  while (pending.length) {
+    const item = pending.pop();
+    if (isTemplate(item)) return true;
+    if (item instanceof Struct) pending.push(...item.args);
+  }
+  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)) {
+    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 (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);
+  } 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);
+}
+
+export function expandTemplates(sources) {
+  const expanded = [...sources];
+  for (let index = 0; index < expanded.length; index++) {
+    const source = expanded[index];
+    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)) {
+        throw new EyemindError(`line ${source.line}: rule templates must be top-level conjuncts of an implies() conclusion`);
+      }
+      continue;
+    }
+    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();
+    for (const goal of source.body) variables(goal, outer);
+    for (const head of heads) if (!isTemplate(head)) variables(head, outer);
+    const lowered = heads.map((head) => {
+      if (!isTemplate(head)) {
+        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 premise = normalizeGoal(head.args[forward ? 0 : 1]);
+      const conclusion = normalizeGoal(head.args[forward ? 1 : 0]);
+      for (const item of flattenConjunction(conclusion)) {
+        if (item === EMPTY || isTerm(item, '.', 2)) {
+          throw new EyemindError(`line ${source.line}: a generated rule conclusion cannot be an empty or open list`);
+        }
+      }
+      const body = flattenConjunction(premise);
+      for (const goal of body) checkGoal(goal, source.line);
+      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);
+      for (const generated of conclusions) {
+        expanded.push({
+          kind: forward ? 'forward' : 'backward', head: generated, body: [activation, ...body],
+          line: source.line, file: source.file, captures: captured.map((variable) => variable.name),
+        });
+      }
+      return activation;
+    });
+    expanded[index] = { ...source, head: conjunction(lowered) };
+  }
+  return expanded;
+}

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