eyelang 0.1.5 → 0.1.7

package/README.md

@@ -9,12 +9,26 @@ It grew out of logic-language experiments in the EYE/N3 reasoning tradition, but
 
 ## Install and run
 
+Eyelang has no runtime npm dependencies and no build step. From a source checkout, run the CLI directly with Node.js 18 or newer:
+
+```bash
+node bin/eyelang.js examples/ancestor.pl
+node bin/eyelang.js --proof examples/socrates.pl
+printf 'works(stdin, true) :- eq(ok, ok).\n' | node bin/eyelang.js -
+```
+
+For one-off local CLI use from the checkout, npm can run the package bin without a manual symlink:
+
+```bash
+npm exec -- eyelang --version
+npm exec -- eyelang examples/ancestor.pl
+```
+
+To install the checkout's `eyelang` command on your `PATH`, use npm's package link:
+
 ```bash
-npm install
-eyelang examples/ancestor.pl
-eyelang --proof examples/socrates.pl
-printf 'works(stdin, true) :- eq(ok, ok).
-' | eyelang -
+npm link
+eyelang --version
 ```
 
 ## JavaScript API

package/docs/guide.md

@@ -1,6 +1,6 @@
 # Eyelang Guide
 
-This guide introduces Eyelang, a small Horn-clause language and engine whose source syntax is a deliberate subset of ordinary Prolog syntax for rules, goals, answers, and proofs. Eyelang works over ordinary terms, lists, arithmetic, strings, and finite search. Run it with the `eyelang` CLI, or use `node src/bin.js` when working directly from a source checkout.
+This guide introduces Eyelang, a small Horn-clause language and engine whose source syntax is a deliberate subset of ordinary Prolog syntax for rules, goals, answers, and proofs. Eyelang works over ordinary terms, lists, arithmetic, strings, and finite search. Run it with the `eyelang` CLI, or use `node bin/eyelang.js` when working directly from a source checkout.
 
 Programs write relations directly, for example `ancestor(pat, emma)` or `status(case1, accepted)`. Eyelang output is ordinary Eyelang syntax: by default, the CLI materializes selected answer facts and prints those facts only. Pass `--proof` (or `-p`) when you also want each answer followed by a `why/2` explanation fact that records the proof. Programs may add `materialize(Name, Arity).` declarations to focus output on selected predicates.
 
@@ -24,25 +24,35 @@ For the normative language definition, including lexical syntax, terms, clauses,
 
 ## Quick start
 
-Install dependencies, then run the Eyelang CLI:
+Eyelang has no runtime npm dependencies and no build step. From a source checkout, run the CLI entry point directly with Node.js 18 or newer:
 
 ```sh
-npm install
+node bin/eyelang.js --version
+node bin/eyelang.js examples/ancestor.pl
+node bin/eyelang.js facts.pl rules.pl
+printf 'works(stdin, true) :- eq(ok, ok).\n' | node bin/eyelang.js -
 ```
 
-There is no build step for the source-checkout CLI path. Run examples, multiple inputs, stdin, or a URL:
+You can also use npm's local package-bin runner from the checkout:
 
 ```sh
+npm exec -- eyelang --version
+npm exec -- eyelang examples/ancestor.pl
+```
+
+To make the `eyelang` command available on your `PATH` while developing this checkout, prefer npm's package link instead of a manual symlink:
+
+```sh
+npm link
 eyelang --version
-eyelang examples/ancestor.pl
-eyelang facts.pl rules.pl
-printf 'works(stdin, true) :- eq(ok, ok).\n' | eyelang -
 ```
 
-The CLI runs directly on Node.js 18 or newer. From a source checkout, `node src/bin.js` exposes the same options.
+`npm install -g .` is another local-checkout option if you want npm to install the package globally instead of linking it. Avoid hand-written `/usr/local/bin` symlinks unless you really need one; npm already reads the `bin` entry in `package.json` and creates the correct executable shim.
 
 ## Running eyelang
 
+The commands in this section use `eyelang` for readability. In a source checkout where you have not run `npm link` or `npm install -g .`, replace `eyelang` with `node bin/eyelang.js`, or run the command through `npm exec -- eyelang`.
+
 Show the package version:
 
 ```sh
@@ -238,7 +248,7 @@ The playground has matching `--stats` and `--proof` checkboxes, so browser runs
 
 ### Builtins
 
-Eyelang builtins are registered by name and arity in small modules under [`src/builtins`](../src/builtins). This keeps the runtime portable to Node.js and the browser while giving each builtin family a clear boundary. Built-ins are called as ordinary Eyelang predicates. See the [Eyelang language reference](docs/language-reference.md#9-standard-built-in-predicates) for the portable profile. The bundled implementation currently registers 80 name/arity entries across 78 predicate names:
+Eyelang builtins are registered by name and arity in small modules under [`src/builtins`](../src/builtins). This keeps the runtime portable to Node.js and the browser while giving each builtin family a clear boundary. Built-ins are called as ordinary Eyelang predicates. See the [Eyelang language reference](language-reference.md#9-standard-built-in-predicates) for the portable profile. The bundled implementation currently registers 80 name/arity entries across 78 predicate names:
 
 | Family | Count | Built-ins |
 |---|---:|---|
@@ -289,8 +299,6 @@ Use `holds/2` when you want to match the member term directly, for example `name
 
 `matches/3` can create context data from named regular-expression captures, which is useful when text logs or messages need to become facts before later rules inspect them with `holds/2` or `holds/3`. See [`observability-log-correlation.pl`](../examples/observability-log-correlation.pl) for a complete log-correlation example.
 
-The N3 counterpart of the context schema audit lives at [`examples/context-schema-audit.n3`](../examples/context-schema-audit.n3) with golden output in [`examples/output/context-schema-audit.md`](../examples/output/context-schema-audit.md).
-
 
 ## Example catalog
 
@@ -321,6 +329,7 @@ The repository includes examples for recursion, graph reachability, finite searc
 | [`canary-release.pl`](../examples/canary-release.pl) | Decides canary rollout or rollback. | [`output/canary-release.pl`](../examples/output/canary-release.pl) |
 | [`cat-koko.pl`](../examples/cat-koko.pl) | Demonstrates named existential witnesses from a Cat Koko rule pattern. | [`output/cat-koko.pl`](../examples/output/cat-koko.pl) |
 | [`clinical-trial-screening.pl`](../examples/clinical-trial-screening.pl) | Screens candidates for a trial. | [`output/clinical-trial-screening.pl`](../examples/output/clinical-trial-screening.pl) |
+| [`collatz-1000.pl`](../examples/collatz-1000.pl) | Materializes Collatz trajectories for starts 1000 down to 1. | [`output/collatz-1000.pl`](../examples/output/collatz-1000.pl) |
 | [`combinatorics-findall-sort.pl`](../examples/combinatorics-findall-sort.pl) | Collects and sorts finite combinations. | [`output/combinatorics-findall-sort.pl`](../examples/output/combinatorics-findall-sort.pl) |
 | [`competitive-enzyme-kinetics.pl`](../examples/competitive-enzyme-kinetics.pl) | Computes inhibited enzyme reaction rates. | [`output/competitive-enzyme-kinetics.pl`](../examples/output/competitive-enzyme-kinetics.pl) |
 | [`complex.pl`](../examples/complex.pl) | Performs arithmetic on complex pairs. | [`output/complex.pl`](../examples/output/complex.pl) |
@@ -467,8 +476,8 @@ The conformance suite lives in [`test/conformance/`](../test/conformance/) as on
 Common commands:
 
 ```sh
-npm run test:eyelang        # integration check plus eyelang corpus
-npm run test:eyelang:corpus # conformance, regression/API/white-box, examples, and proof examples
+npm run test:eyelang        # alias for npm test
+npm test                    # full conformance, regression/API/white-box, examples, and proof examples
 node test/run-conformance.mjs
 node test/run-regression.mjs
 node test/run-examples.mjs

package/docs/language-reference.md

@@ -39,7 +39,7 @@
   - [9.6 Strings and atom constants](#96-strings-and-atom-constants)
   - [9.7 Lists](#97-lists)
   - [9.8 Aggregation and ordering](#98-aggregation-and-ordering)
-  - [9.9 Context terms](#99-context-terms)
+  - [9.9 Context and term inspection](#99-context-and-term-inspection)
   - [9.10 Search control](#910-search-control)
 - [10. Implementation-specific built-ins](#10-implementation-specific-built-ins)
 - [11. Declarations](#11-declarations)
@@ -475,8 +475,6 @@ The first goal can yield `holds((name(alice, "Alice"), knows(alice, bob)), name(
 
 `holds/3` is the appropriate form for schema-style introspection because it exposes the predicate name and all arguments without assuming a fixed arity. For example, a single rule can inspect `heartbeat`, `source(sensor17)`, `temperature(sensor17, 38)`, and `signature(sensor17, sha256, Hash, Time)` as `heartbeat/0`, `source/1`, `temperature/2`, and `signature/4`; see [`context-schema-audit.pl`](../examples/context-schema-audit.pl).
 
-The N3 example [`context-schema-audit.n3`](../examples/context-schema-audit.n3) shows the same idea in quoted graph form: members are encoded as predicates with RDF-list argument objects, then `log:includes` and `list:length` expose `Name + Arity` for schema checking.
-
 ### 9.10 Search control
 
 | Built-in | Meaning |

package/examples/collatz-1000.pl

@@ -0,0 +1,45 @@
+% Collatz conjecture suite translated from Eyeling's examples/collatz-1000.n3.
+% It enumerates starts N = 1000, 999, ..., 1 by deriving N = 1000 - N0
+% from a repeat relation, then materializes each full trajectory.
+%
+% Source N3:
+% https://raw.githubusercontent.com/eyereasoner/eyeling/refs/heads/main/examples/collatz-1000.n3
+
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
+% memoize/2 caches shared suffix trajectories so the 1000 starts do not recompute
+% the same Collatz tails hundreds of times.
+materialize(collatzTrajectory, 2).
+memoize(collatz, 2).
+
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% The N3 source defines repeat/2 recursively; this Eyelang version uses the
+% equivalent bounded generator so the 1000-case regression remains stack-safe.
+
+% Query / materialization of the test suite.
+% Generate N in {1000..1} and ask the backward-defined collatz/2 predicate
+% for the full trajectory list M.
+collatzTrajectory(N, M) :-
+  repeat(1000, N0),
+  sub(1000, N0, N),
+  collatz(N, M).
+
+% Range generator.
+% repeat(N, I) enumerates all integers I in the half-open interval [0..N-1].
+repeat(N, I) :-
+  sub(N, 1, Last),
+  between(0, Last, I).
+
+% Backward Collatz relation.
+% collatz(N, M) relates a start value N to its full trajectory list M.
+collatz(1, [1]).
+collatz(N, [N|J]) :-
+  gt(N, 1),
+  mod(N, 2, 0),
+  div(N, 2, N1),
+  collatz(N1, J).
+collatz(N, [N|J]) :-
+  gt(N, 1),
+  mod(N, 2, 1),
+  mul(3, N, T),
+  add(T, 1, N1),
+  collatz(N1, J).