eyeprolog 1.6.13 → 1.6.15

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/examples/output/takeuchi.pl

@@ -1 +1 @@
-tak([34, 13, 8], 13).
+tak([16, 11, 6], 11).

package/examples/proof/iso-reflective-terms.pl

@@ -0,0 +1,80 @@
+report(shape, shape(event, 2)).
+report(payload, reading(temperature, 21)).
+report(parts, [event, sensor_7, reading(temperature, 21)]).
+report(rebuilt, alert(sensor_7, high)).
+report(variable_count, 3).
+report(copied_shape, same_but_fresh).
+report(order, <).
+
+clause(1, sample(event(sensor_7, reading(temperature, 21))), true).
+clause(2,
+       report(shape, shape(var('Name'), var('Arity'))),
+       (sample(var('Term')), functor(var('Term'), var('Name'), var('Arity')))).
+clause(3,
+       report(payload, var('Payload')),
+       (sample(var('Term')), arg(2, var('Term'), var('Payload')))).
+clause(4, report(parts, var('Parts')), (sample(var('Term')), var('Term') =.. var('Parts'))).
+clause(5, report(rebuilt, var('Term')), var('Term') =.. [alert, sensor_7, high]).
+clause(6,
+       report(variable_count, var('Count')),
+       (term_variables(rule(var('X'), pair(var('X'), anonymous(1)), anonymous(2)), var('Variables')),
+        var('Variables') = [anonymous(3), anonymous(4), anonymous(5)],
+        var('Count') = 3)).
+clause(7,
+       report(copied_shape, same_but_fresh),
+       (copy_term(pair(var('X'), var('X')), pair(var('A'), var('B'))),
+        var('A') == var('B'),
+        var('X') \== var('A'))).
+clause(8, report(order, var('Order')), compare(var('Order'), alpha, beta)).
+
+step(report(shape, shape(event, 2)),
+     rule(2),
+     ['Name' = event, 'Arity' = 2, 'Term' = event(sensor_7, reading(temperature, 21))],
+     [sample(event(sensor_7, reading(temperature, 21))),
+      functor(event(sensor_7, reading(temperature, 21)), event, 2)]).
+step(sample(event(sensor_7, reading(temperature, 21))), fact(1), [], []).
+step(functor(event(sensor_7, reading(temperature, 21)), event, 2), builtin, [], []).
+step(report(payload, reading(temperature, 21)),
+     rule(3),
+     ['Payload' = reading(temperature, 21), 'Term' = event(sensor_7, reading(temperature, 21))],
+     [sample(event(sensor_7, reading(temperature, 21))),
+      arg(2, event(sensor_7, reading(temperature, 21)), reading(temperature, 21))]).
+step(arg(2, event(sensor_7, reading(temperature, 21)), reading(temperature, 21)),
+     builtin,
+     [],
+     []).
+step(report(parts, [event, sensor_7, reading(temperature, 21)]),
+     rule(4),
+     ['Parts' = [event, sensor_7, reading(temperature, 21)],
+      'Term' = event(sensor_7, reading(temperature, 21))],
+     [sample(event(sensor_7, reading(temperature, 21))),
+      event(sensor_7, reading(temperature, 21)) =.. [event, sensor_7, reading(temperature, 21)]]).
+step(event(sensor_7, reading(temperature, 21)) =.. [event, sensor_7, reading(temperature, 21)],
+     builtin,
+     [],
+     []).
+step(report(rebuilt, alert(sensor_7, high)),
+     rule(5),
+     ['Term' = alert(sensor_7, high)],
+     [alert(sensor_7, high) =.. [alert, sensor_7, high]]).
+step(alert(sensor_7, high) =.. [alert, sensor_7, high], builtin, [], []).
+step(report(variable_count, 3),
+     rule(6),
+     ['Count' = 3, 'Variables' = [__anon0, __anon1, __anon2]],
+     [term_variables(rule(X, pair(X, _Y), _Z), [X, _Y, _Z]),
+      [__anon0, __anon1, __anon2] = [__anon0, __anon1, __anon2],
+      3 = 3]).
+step(term_variables(rule(X, pair(X, _Y), _Z), [X, _Y, _Z]), builtin, [], []).
+step([__anon0, __anon1, __anon2] = [__anon0, __anon1, __anon2], builtin, [], []).
+step(3 = 3, builtin, [], []).
+step(report(copied_shape, same_but_fresh),
+     rule(7),
+     [],
+     [copy_term(pair(X, X), pair(__copy1_0, __copy1_0)),
+      __copy1_0 == __copy1_0,
+      X \== __copy1_0]).
+step(copy_term(pair(X, X), pair(__copy1_0, __copy1_0)), builtin, [], []).
+step(__copy1_0 == __copy1_0, builtin, [], []).
+step(X \== __copy1_0, builtin, [], []).
+step(report(order, <), rule(8), ['Order' = (<)], [compare(<, alpha, beta)]).
+step(compare(<, alpha, beta), builtin, [], []).

package/examples/proof/iso-term-io.pl

@@ -0,0 +1,87 @@
+report(first_term, event(sensor_7, online)).
+report(variable_metadata, checked).
+report(reached_end, yes).
+
+clause(2, fixture_path('/tmp/eyeprolog-iso-term-io-example.pl'), true).
+clause(4,
+       report(first_term, var('Term')),
+       (fixture_path(var('Path')),
+        open(var('Path'), read, var('Stream'), []),
+        read(var('Stream'), var('Term')),
+        close(var('Stream')))).
+clause(5,
+       report(variable_metadata, checked),
+       (fixture_path(var('Path')),
+        open(var('Path'), read, var('Stream'), []),
+        read(var('Stream'), anonymous(1)),
+        read_term(var('Stream'), rule(var('A'), var('A'), var('B')), [variables([var('A'), var('B')]), variable_names([var('NameA') = var('A'), var('NameB') = var('B')]), singletons([var('NameB') = var('B')])]),
+        atom(var('NameA')),
+        atom(var('NameB')),
+        var('NameA') \== var('NameB'),
+        close(var('Stream')))).
+clause(6,
+       report(reached_end, yes),
+       (fixture_path(var('Path')),
+        open(var('Path'), read, var('Stream'), [eof_action(eof_code)]),
+        read(var('Stream'), anonymous(1)),
+        read(var('Stream'), anonymous(2)),
+        read(var('Stream'), end_of_file),
+        at_end_of_stream(var('Stream')),
+        close(var('Stream')))).
+
+step(report(first_term, event(sensor_7, online)),
+     rule(4),
+     ['Term' = event(sensor_7, online),
+      'Path' = '/tmp/eyeprolog-iso-term-io-example.pl',
+      'Stream' = '$stream'(1)],
+     [fixture_path('/tmp/eyeprolog-iso-term-io-example.pl'),
+      open('/tmp/eyeprolog-iso-term-io-example.pl', read, '$stream'(1), []),
+      read('$stream'(1), event(sensor_7, online)),
+      close('$stream'(1))]).
+step(fixture_path('/tmp/eyeprolog-iso-term-io-example.pl'), fact(2), [], []).
+step(open('/tmp/eyeprolog-iso-term-io-example.pl', read, '$stream'(1), []), builtin, [], []).
+step(read('$stream'(1), event(sensor_7, online)), builtin, [], []).
+step(close('$stream'(1)), builtin, [], []).
+step(report(variable_metadata, checked),
+     rule(5),
+     ['Path' = '/tmp/eyeprolog-iso-term-io-example.pl',
+      'Stream' = '$stream'(2),
+      'NameA' = '_A',
+      'NameB' = '_B'],
+     [fixture_path('/tmp/eyeprolog-iso-term-io-example.pl'),
+      open('/tmp/eyeprolog-iso-term-io-example.pl', read, '$stream'(2), []),
+      read('$stream'(2), event(sensor_7, online)),
+      read_term('$stream'(2), rule(_read_3_0, _read_3_0, _read_3_1), [variables([_read_3_0, _read_3_1]), variable_names(['_A' = _read_3_0, '_B' = _read_3_1]), singletons(['_B' = _read_3_1])]),
+      atom('_A'),
+      atom('_B'),
+      '_A' \== '_B',
+      close('$stream'(2))]).
+step(open('/tmp/eyeprolog-iso-term-io-example.pl', read, '$stream'(2), []), builtin, [], []).
+step(read('$stream'(2), event(sensor_7, online)), builtin, [], []).
+step(read_term('$stream'(2), rule(_read_3_0, _read_3_0, _read_3_1), [variables([_read_3_0, _read_3_1]), variable_names(['_A' = _read_3_0, '_B' = _read_3_1]), singletons(['_B' = _read_3_1])]),
+     builtin,
+     [],
+     []).
+step(atom('_A'), builtin, [], []).
+step(atom('_B'), builtin, [], []).
+step('_A' \== '_B', builtin, [], []).
+step(close('$stream'(2)), builtin, [], []).
+step(report(reached_end, yes),
+     rule(6),
+     ['Path' = '/tmp/eyeprolog-iso-term-io-example.pl', 'Stream' = '$stream'(4)],
+     [fixture_path('/tmp/eyeprolog-iso-term-io-example.pl'),
+      open('/tmp/eyeprolog-iso-term-io-example.pl', read, '$stream'(4), [eof_action(eof_code)]),
+      read('$stream'(4), event(sensor_7, online)),
+      read('$stream'(4), rule(_read_5_0, _read_5_0, _read_5_1)),
+      read('$stream'(4), end_of_file),
+      at_end_of_stream('$stream'(4)),
+      close('$stream'(4))]).
+step(open('/tmp/eyeprolog-iso-term-io-example.pl', read, '$stream'(4), [eof_action(eof_code)]),
+     builtin,
+     [],
+     []).
+step(read('$stream'(4), event(sensor_7, online)), builtin, [], []).
+step(read('$stream'(4), rule(_read_5_0, _read_5_0, _read_5_1)), builtin, [], []).
+step(read('$stream'(4), end_of_file), builtin, [], []).
+step(at_end_of_stream('$stream'(4)), builtin, [], []).
+step(close('$stream'(4)), builtin, [], []).