eyelang 0.1.6 → 0.1.8

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
@@ -319,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) |
@@ -504,7 +515,17 @@ A useful rule of thumb:
 | Human-auditable derivations | Either | Both can emit proof explanations when requested. |
 | Large generated Horn-clause workloads | eyelang | The engine specializes in predicate/arity indexing, scalar argument indexes, fast fact paths, and materialized output goals. |
 
-For the deep taxonomy benchmark, Eyelang is substantially faster in current local checks. On one sandbox run, `eyelang examples/deep-taxonomy-100000.pl > /dev/null` took about `1.60 sec`, while `eyeling` package version `1.28.7` on `examples/deep-taxonomy-100000.n3` took about `4.56 sec` without proof and about `5.04 sec` with proof. Treat those numbers as a smoke comparison rather than a formal benchmark: hardware, Node.js version, package version, and CLI startup all matter.
+On local smoke benchmarks, eyelang is substantially faster on large generated Horn-clause and recursion-heavy workloads. These numbers are 5-run medians with stdout redirected to `/dev/null`, using Node.js `v22.16.0`, eyelang from this checkout, and Eyeling package version `1.34.6` with its default output mode. The ratio is `Eyeling median / eyelang median`, so larger numbers mean eyelang was faster.
+
+| Example | eyelang median | Eyeling median | Ratio |
+| --- | ---: | ---: | ---: |
+| `fundamental-theorem-arithmetic` | `0.16 sec` | `2.00 sec` | `12.66x` |
+| `deep-taxonomy-100000` | `1.69 sec` | `4.72 sec` | `2.79x` |
+| `path-discovery` | `0.53 sec` | `1.62 sec` | `3.07x` |
+| `fibonacci` | `0.15 sec` | `5.76 sec` | `38.40x` |
+| `collatz-1000` | `0.71 sec` | `6.99 sec` | `9.85x` |
+
+Treat these as smoke comparisons rather than a formal benchmark: hardware, Node.js version, package version, CLI startup, and output mode all matter.
 
 The projects are therefore complementary rather than replacements for each other: Eyeling optimizes for Semantic Web interoperability and N3 expressiveness; eyelang optimizes for a small standard-looking relational rule language and fast finite goal-directed execution.
 

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).