eyeprolog 1.6.14 → 1.6.16

package/README.md

@@ -64,6 +64,7 @@ printf 'human(socrates).\nmortal(X) :- human(X).\n' |
 
 - [The Art of EyeProlog](https://eyereasoner.github.io/eyeprolog/the-art-of-eyeprolog) — complete reference
 - [Why EyeProlog?](https://eyereasoner.github.io/eyeprolog/why-eyeprolog) — project scope and design
+- [ARC in EyeProlog](https://eyereasoner.github.io/eyeprolog/arc-in-eyeprolog) — answer, reason, check
 - [Playground](https://eyereasoner.github.io/eyeprolog/playground) — run EyeProlog in a browser
 - [Examples](examples) — runnable programs and checked output
 - [Example decks](examples/deck/README.md) — explainable RDF/Prolog scenarios with reproducible roundtrips

package/arc-in-eyeprolog.md

@@ -0,0 +1,226 @@
+# ARC in EyeProlog — answer, reason, check
+
+> Ask the right question. Get the answer. Understand the reason. Run the check.
+
+[ARC](https://josd.github.io/arc/) turns a precise question into a portable,
+executable artifact that answers it, explains the derivation, and checks the
+result through a route capable of finding errors. This page is that pattern
+written in EyeProlog's own terms, where the artifact is an ordinary Prolog
+program, the reason is ordinary Prolog data, and the check is a command.
+
+## 01 — Motivation: why a reasoner should check itself
+
+Answers are cheap. Trustworthy answers are not.
+
+A rule engine that returns `true` has told you that some search succeeded. It
+has not told you which rules fired, which facts they rested on, or whether the
+arithmetic along the way was right. In most workflows verification is a manual
+afterthought: read the output, redo the calculation by hand, ask whoever wrote
+the rules.
+
+EyeProlog moves that work into the artifact:
+
+```text
+typical workflow    program → answer → someone checks it by hand
+EyeProlog           program → answer + proof → checked mechanically
+```
+
+This puts the valuable human work upstream — stating the question precisely,
+choosing the facts, writing the rules honestly — and leaves the mechanical
+work to something that can be run again tomorrow.
+
+An answer does not become trustworthy by being emitted confidently. It becomes
+trustworthy by being inspectable, repeatable, and able to be shown wrong.
+
+## 02 — Pattern: how an EyeProlog arc works
+
+Every arc starts from three explicit inputs, and in EyeProlog all three live in
+one file:
+
+- **Question** — what do we want to decide? Written as a goal: `%% ?- ageAbove(X0, X1).`
+- **Data** — the facts: `birthDay(patH, '1944-08-21').`
+- **Logic** — the rules: `ageAbove(S, A) :- birthDay(S, B), ..., F @> A.`
+
+From those it produces three outputs:
+
+```text
+INPUT                          OUTPUT
+Question ─┐                    ┌─ Answer   what follows
+Data ─────┼─→ EyeProlog ───────┼─ Reason   why it follows
+Logic ────┘                    └─ Check    whether that why holds
+```
+
+Run against [`examples/age.pl`](examples/age.pl), the three are three commands:
+
+```sh
+eyeprolog examples/age.pl                                 # Answer
+eyeprolog --proof examples/age.pl                         # Reason
+eyeprolog examples/age.pl --check-proof examples/proof/age.pl   # Check
+```
+
+```text
+ageAbove(patH, 'P80Y').
+checked: 7 steps, 2 recomputed.
+```
+
+The question is part of the specification, not a prompt. `%% ?- ageAbove(X0, X1).`
+is precise enough to distinguish a right answer, a wrong answer, and a right
+answer to a different question — and it stays in the file, so the artifact
+carries what it was asked.
+
+Nothing here is trapped in a session. The program is a text file, the proof is
+a text file of ordinary Prolog facts, and the check is a process exit status.
+
+## 03 — Trust: the check is the trust contract
+
+An explanation is not verification. A convincing explanation can be produced
+for a wrong result, so the check must be capable of **disagreeing** with the
+answer.
+
+A proof document is read as a claim, not believed. `--check-proof` tests five
+conditions:
+
+| | condition | what it establishes |
+| --- | --- | --- |
+| **C1** | Resolution | every checked step really is an instance of the clause it cites — and the clause is taken from the program, not from the document, so a proof cannot be made valid by restating the rule it used |
+| **C2** | Well-founded | following what a step used never leads back to it; a proof that rested on itself would prove anything |
+| **C3** | Justification | every step carries exactly one known justification |
+| **C4** | Coverage | every claim has a step, and every use resolves to a step or to a statement the program gives |
+| **C5** | Re-decision | a step the document only *asserts* is computed again, independently, and must agree |
+
+C5 is the trust contract. The largest class of steps in a typical proof is the
+primitive — arithmetic, comparison, string and date operations that no clause
+derives. Reading a document cannot tell whether those are true, so they are run
+again against a program holding the bundled libraries and **nothing else**. No
+clause of the theory under proof is present, which means the recomputation
+cannot be talked into agreeing by the very rules it is auditing.
+
+This is ARC's "genuinely different route", made concrete: not a second
+implementation of the same reasoning, but the same primitive decided by a
+process that has been denied the theory.
+
+The difference is not theoretical. A document can pass C1 through C4 completely
+— every step a proper instance, every use accounted for, no cycles — and still
+record a computed value that is simply false, provided it tells the same lie
+throughout. Only recomputation catches that one. There is a regression test
+that constructs exactly such a document and requires the checker to reject it,
+with C5 as the only objecting condition.
+
+A condition that cannot fail is not much of a check.
+
+## 04 — Composition: a checked answer is data
+
+An arc need not stay isolated. Its output is the same kind of thing as its
+input, which is what lets arcs compose.
+
+A proof document is not a log; it is a set of ground Prolog facts — `step/4`,
+`clause/3`, and the claims themselves. That means the checked answer of one
+program can be loaded as the data of the next, and a program can reason *about*
+a proof as readily as it reasons about anything else.
+
+```text
+program A ──→ answer + proof ──┐
+program B ──→ answer + proof ──┼──→ program C ──→ answer + proof + check
+facts     ────────────────────-┘
+```
+
+The same property connects EyeProlog to the wider data world. RDF quads convert
+to ordinary `rdf/4` facts and back, so an arc can take RDF in, reason in
+Prolog, and emit RDF out, with the proof of the middle step available for
+inspection. The contract at each boundary is explicit, so a larger arc can
+check not only its own result but whether the pieces compose into an answer to
+the larger question.
+
+## 05 — Scope: what this can and cannot guarantee
+
+Checking makes trust testable. It does not make computation infallible, and
+the checker says which is which rather than folding everything into an
+undifferentiated success.
+
+- A check is only as strong as its independence. C5's independence comes from
+  excluding the theory under proof; that same exclusion is why some steps
+  cannot be recomputed at all.
+- **Reflective** goals — those reading the program's own database or operator
+  table — are outside C5 by construction, since that is exactly what it
+  excludes.
+- **Stateful** goals — an attributed variable, a constraint store, an open
+  stream — depend on state the original run accumulated. Re-running stream
+  operations would also perform I/O, and a checker must not have side effects.
+- These remain **obligations**: named individually in the checker, counted
+  separately in the result, and reported as what the check rests on rather
+  than what it establishes.
+- A proof does not authenticate its source data. Correct reasoning over wrong
+  facts gives a correctly derived wrong answer.
+- Negation as failure means a goal did not succeed. It does not establish that
+  the negated statement is false.
+- Explicit rules can still encode the wrong policy. Being able to read the
+  derivation is what makes that reviewable.
+
+Human judgment stays essential, particularly in choosing the question and
+deciding what evidence is enough.
+
+## 06 — Applications: where this fits
+
+Rule-driven work with explicit structure and testable correctness conditions:
+
+- tracing a policy decision back to the facts and rules that produced it;
+- recomputing an engineering or numeric result by an independent route;
+- checking a derivation against invariants, bounds, or known identities;
+- auditing a decision months later, from the proof alone, without rerunning
+  the search that found it;
+- carrying a checked result across a system boundary, where the recipient
+  trusts neither the sender nor the sender's engine.
+
+That last one is the case a proof is really for. The recipient does not have to
+trust the engine that produced the answer — they can check the document against
+the program themselves, with a different copy of the checker if they like.
+
+## 07 — Practice: design principles
+
+- **Question first** — state the goal in the file, not in a shell history.
+- **Answer directly** — the answer is a term, not prose about a term.
+- **Explain the derivation** — record the clause, the bindings, and what each
+  step rested on.
+- **Check independently** — recompute what the document merely asserts, from a
+  position that cannot reuse the theory.
+- **Fail visibly** — a proof that cannot be explained records the answer as
+  `unproven` rather than omitting it.
+- **Name what is trusted** — an obligation counted and labelled is honest; an
+  obligation folded into a success is not.
+- **Prefer executable verification** — checking runs in the test suite, not in
+  someone's afternoon.
+- **Keep artifacts self-contained** — program, answer, and proof are three
+  files that can be read and rerun without the machine that made them.
+
+## 08 — Catalogue: the corpus
+
+The pattern is not aspirational here. Every one of the **235 examples** ships
+with its answer and a checked proof, and `npm test` re-checks all of them on
+every run:
+
+| | |
+| --- | ---: |
+| examples | 235 |
+| packaged proofs | 235 |
+| recorded steps | 36423 |
+| verified against a source clause | 20746 |
+| recomputed independently | 14720 |
+| remaining obligations | 952 (2.6%) |
+
+The proof directory is read from disk rather than from a list, so a document
+cannot be added without being checked. An unverified proof is worse than none,
+because it still looks like evidence.
+
+Worth reading in order: [`examples/age.pl`](examples/age.pl) for the smallest
+complete arc, [`examples/deontic-logic.pl`](examples/deontic-logic.pl) for a
+policy decision traced to its rules, and
+[`examples/clpz-n-queens.pl`](examples/clpz-n-queens.pl) for a proof of a
+constrained search.
+
+## References
+
+- [ARC — answer, reason, check](https://josd.github.io/arc/), the pattern this
+  page follows
+- [Why EyeProlog?](why-eyeprolog.md), the same argument in the setting of an
+  ISO Prolog implementation
+- [The Art of EyeProlog](the-art-of-eyeprolog.md), the implementation reference

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.6.14",
+  "version": "1.6.16",
   "description": "EyeProlog turns facts and rules into answers and proofs.",
   "type": "module",
   "main": "./index.js",
@@ -28,6 +28,7 @@
   "files": [
     "LICENSE.md",
     "README.md",
+    "arc-in-eyeprolog.md",
     "index.js",
     "index.d.ts",
     "playground.html",

package/src/check-proof.js

@@ -351,8 +351,10 @@ export function checkProofDocument(program, text) {
       failures.push({ condition: 'C4', conclusion: key(claim), detail: 'claimed, but no step concludes it' });
     }
   }
+  let uses = 0;
   for (const step of steps) {
     for (const use of step.uses) {
+      uses++;
       if (byConclusion.has(key(use)) || given.has(key(use))) continue;
       failures.push({ condition: 'C4', conclusion: key(step.conclusion), detail: `uses ${key(use)}, which nothing concludes and the program does not give` });
     }
@@ -360,7 +362,57 @@ export function checkProofDocument(program, text) {
 
   checkWellFounded(byConclusion, failures);
 
-  return { valid: failures.length === 0, steps: steps.length, verified, redecided, trusted, failures, claims: claims.length };
+  const failed = (condition) => failures.filter((failure) => failure.condition === condition).length;
+  // What each condition covered, so a reader can see the shape of the check
+  // rather than only its verdict. A condition that examined nothing says so:
+  // "0 steps" is information, not a pass.
+  const conditions = [
+    { id: 'C1', name: 'Resolution', covered: verified, failed: failed('C1'),
+      summary: `${verified} step(s) re-performed against the source clause they cite` },
+    { id: 'C2', name: 'Well-founded', covered: steps.length, failed: failed('C2'),
+      summary: `${steps.length} step(s) checked for a conclusion resting on its own derivation` },
+    { id: 'C3', name: 'Justification', covered: steps.length, failed: failed('C3'),
+      summary: `${steps.length} step(s) carrying exactly one known justification` },
+    { id: 'C4', name: 'Coverage', covered: claims.length + uses, failed: failed('C4'),
+      summary: `${claims.length} claim(s) and ${uses} use(s) resolved to a step or to a statement the program gives` },
+    { id: 'C5', name: 'Re-decision', covered: redecided, failed: failed('C5'),
+      summary: `${redecided} step(s) recomputed against a program holding no clause of the theory` },
+  ];
+
+  return {
+    valid: failures.length === 0,
+    steps: steps.length,
+    verified,
+    redecided,
+    uses,
+    trusted,
+    failures,
+    claims: claims.length,
+    conditions,
+  };
+}
+
+// The condition-by-condition account, as lines. The obligations are listed
+// under C5 because that is the condition they escaped: a step recorded as
+// `builtin` that recomputation could not decide, or one whose justification
+// puts it outside recomputation altogether.
+export function conditionReport(report) {
+  const lines = [];
+  for (const condition of report.conditions ?? []) {
+    const mark = condition.failed > 0 ? `${condition.failed} failure(s)` : 'ok';
+    lines.push(`  ${condition.id} ${condition.name.padEnd(13)} ${mark.padEnd(14)} ${condition.summary}`);
+  }
+  const obligations = report.trusted ?? [];
+  if (obligations.length > 0) {
+    const byReason = new Map();
+    for (const item of obligations) {
+      const reason = item.reason ?? item.kind;
+      byReason.set(reason, (byReason.get(reason) ?? 0) + 1);
+    }
+    const parts = [...byReason].map(([reason, count]) => `${count} ${reason}`).join(', ');
+    lines.push(`  -- ${obligations.length} obligation(s) the check rests on rather than establishes: ${parts}`);
+  }
+  return lines;
 }
 
 // The program's clauses, numbered from 1 in load order -- the numbering

package/src/cli.js

@@ -252,16 +252,20 @@ export async function main(argv) {
   }
 
   if (options.checkProof != null) {
-    const { checkProofDocument, verdict } = await import('./check-proof.js');
+    const { checkProofDocument, conditionReport, verdict } = await import('./check-proof.js');
     const proofText = await fs.readFile(options.checkProof, 'utf8');
     const report = checkProofDocument(program, proofText);
     if (report.steps === 0) throw new Error(`no step/4 proof step found in ${options.checkProof}`);
     if (!report.valid) {
+      // The conditions go to stderr alongside the failures, so a failing run
+      // still says which of the five objected and which held.
+      for (const line of conditionReport(report)) process.stderr.write(`${line}\n`);
       for (const failure of report.failures.slice(0, 5)) {
         process.stderr.write(`  [${failure.condition}] ${failure.conclusion} -- ${failure.detail}\n`);
       }
       throw new Error(`${options.checkProof} is not a valid proof for this program: ${report.failures.length} failure(s)`);
     }
+    if (!options.quiet) for (const line of conditionReport(report)) process.stdout.write(`${line}\n`);
     process.stdout.write(`${verdict(report)}.\n`);
     return;
   }
@@ -396,7 +400,10 @@ Input:
 Options:
   -h, --help            Show this help text and exit.
   -p, --proof           Enable proof explanations.
-  --proof-detail mode   Use abstract or expanded proof detail (implies --proof).
+  --proof-detail mode   abstract stops at a bundled library predicate and records
+                        it as one builtin step; expanded explains through it,
+                        as ordinary source steps. Only differs for a program
+                        that calls a library. (implies --proof)
   --check-proof file    Check a saved proof document against the input program.
   -q, --quads           Run embedded quad tests and fail if any do not hold.
                         Note: -q is quads, not quiet; --quiet has no short form.

package/test/regression/cases-regression.mjs

@@ -4348,15 +4348,28 @@ child.stdin.write(\`consult(${consultedAtom}).\\n\`);
         fs.writeFileSync(proofFile, generated.stdout);
         const verified = runCli(['--check-proof', proofFile, programFile]);
         assertEqual(verified.status, 0, 'verification status');
-        assertEqual(verified.stdout, 'checked: 2 steps.\n', 'verification stdout');
+        // The run accounts for all five conditions and then gives its verdict,
+        // so a reader sees which conditions the result rests on rather than
+        // only that it passed.
+        for (const condition of ['C1 Resolution', 'C2 Well-founded', 'C3 Justification', 'C4 Coverage', 'C5 Re-decision']) {
+          assertIncludes(verified.stdout, condition, `verification reports ${condition}`);
+        }
+        assertEqual(verified.stdout.trimEnd().split('\n').pop(), 'checked: 2 steps.', 'verification verdict');
+        assertEqual(verified.stdout.includes('obligation'), false, 'nothing was left trusted');
+        const quiet = runCli(['--quiet', '--check-proof', proofFile, programFile]);
+        assertEqual(quiet.stdout, 'checked: 2 steps.\n', 'quiet verification stdout is the verdict alone');
         const strictVerified = runCli(['--iso-strict', '--check-proof', proofFile, programFile]);
         assertEqual(strictVerified.status, 0, 'strict verification status');
-        assertEqual(strictVerified.stdout, 'checked: 2 steps.\n', 'strict verification stdout');
+        assertEqual(strictVerified.stdout.trimEnd().split('\n').pop(), 'checked: 2 steps.', 'strict verification verdict');
         const tamperedFile = path.join(temp.dir, `proof-certificate-bad-${++temp.counter}.pl`);
         fs.writeFileSync(tamperedFile, generated.stdout.replace('step(p(a),', 'step(p(b),'));
         const rejected = runCli(['--check-proof', tamperedFile, programFile]);
         assertEqual(rejected.status, 1, 'tampered verification status');
         assertIncludes(rejected.stderr, 'is not a valid proof for this program', 'tampered verification stderr');
+        // A failing run still accounts for every condition, so the report says
+        // which one objected rather than only that something did.
+        assertIncludes(rejected.stderr, 'C1 Resolution', 'tampered run still reports the conditions');
+        assertIncludes(rejected.stderr, 'failure(s)', 'tampered run marks the objecting condition');
       },
     },
     {

package/the-art-of-eyeprolog.md

@@ -1538,10 +1538,14 @@ Checking re-performs each step against the clause it cites: the clause must
 exist, its variables bound as the step recorded them must yield exactly this
 conclusion from exactly these uses, every claim must have a step, every use
 must resolve to a step or to a statement the program gives, and no conclusion
-may rest on itself. `builtin`, `absent`, `collected` and `asserted` steps are
-trusted rather than checked — deciding them again would mean running the
-program, which is what a checker must not do — and the report says how many
-there were rather than folding them into an undifferentiated success. An
+may rest on itself. A `builtin` step derives from no clause, so reading the
+document cannot decide it; it is computed again instead, against a program
+holding the bundled libraries and no clause of the theory under proof, and
+must agree. `absent`, `collected` and `asserted` steps stay trusted: the first
+two range over the theory that recomputation deliberately excludes, and a
+clause asserted at run time is in no source file to check against. The report
+counts what was verified, what was recomputed, and what remains an obligation
+rather than folding them into an undifferentiated success. An
 answer the solver found but the explanation cannot reproduce is recorded as
 `unproven`, which makes the document fail its check, because that is the
 truth about it.