eyeling 1.32.0 → 1.33.0

package/README.md

@@ -22,7 +22,8 @@ Eyeling is characterized by:
 - **Built-ins in rule bodies** — N3 programs can combine logical rules with computations such as math, string, datatype, list, time, and web-oriented predicates.
 - **Streaming RDF Messages** — supports RDF Messages streams, enabling Eyeling to fit into streaming RDF pipelines.
 - **Node.js, npm, and browser use** — run it from the command line, call it from JavaScript, or use the browser-oriented bundle.
-- **RDF-JS interoperability** — use N3 text, RDF-JS quads, datasets, or Eyeling’s own AST-level API.
+- **RDF-JS interoperability** — use N3 text, RDF-JS quads, datasets, or Eyeling’s own AST-level API, with TypeScript declarations grounded in `@rdfjs/types`.
+- **Experimental eyelang engine** — run compact Prolog-style Horn clause programs alongside the N3 engine, giving Eyeling a second reasoning engine without mixing the internals.
 
 
 This README is the primary guide to using, extending, and maintaining Eyeling.
@@ -53,20 +54,21 @@ Eyeling is designed for people who want a small, inspectable reasoner that can r
 4. [Command-line interface](#command-line-interface)
 5. [JavaScript API](#javascript-api)
 6. [RDF-JS integration](#rdf-js-integration)
-7. [RDF compatibility mode and RDF 1.2](#rdf-compatibility-mode-and-rdf-12)
-8. [RDF Message Logs](#rdf-message-logs)
-9. [Built-ins](#built-ins)
-10. [Custom built-ins](#custom-built-ins)
-11. [Reasoning model](#reasoning-model)
-12. [Architecture](#architecture)
-13. [Repository layout](#repository-layout)
-14. [Examples guide](#examples-guide)
-15. [Testing and quality checks](#testing-and-quality-checks)
-16. [Development workflow](#development-workflow)
-17. [Publishing and release notes](#publishing-and-release-notes)
-18. [Troubleshooting](#troubleshooting)
-19. [Security and operational notes](#security-and-operational-notes)
-20. [Glossary](#glossary)
+7. [Eyelang second engine](#eyelang-second-engine)
+8. [RDF compatibility mode and RDF 1.2](#rdf-compatibility-mode-and-rdf-12)
+9. [RDF Message Logs](#rdf-message-logs)
+10. [Built-ins](#built-ins)
+11. [Custom built-ins](#custom-built-ins)
+12. [Reasoning model](#reasoning-model)
+13. [Architecture](#architecture)
+14. [Repository layout](#repository-layout)
+15. [Examples guide](#examples-guide)
+16. [Testing and quality checks](#testing-and-quality-checks)
+17. [Development workflow](#development-workflow)
+18. [Publishing and release notes](#publishing-and-release-notes)
+19. [Troubleshooting](#troubleshooting)
+20. [Security and operational notes](#security-and-operational-notes)
+21. [Glossary](#glossary)
 
 ---
 
@@ -80,7 +82,8 @@ It accepts facts and rules written in N3-style syntax, computes the logical cons
 - a CommonJS API from Node.js through `require('eyeling')`;
 - a browser/worker API through `eyeling/browser`;
 - an RDF-JS adapter for applications that work with quads and data factories;
-- a streaming tool for RDF Message Logs.
+- a streaming tool for RDF Message Logs;
+- an experimental host for the `eyelang` Prolog-style Horn clause engine.
 
 Eyeling is intentionally small and dependency-light. The source tree is organized as a miniature compiler and inference engine: lexer, parser, term model, rule normalization, built-ins, forward chaining, backward proving, printing, RDF-JS adapters, and CLI wiring.
 
@@ -143,6 +146,26 @@ For proof output:
 node eyeling.js --proof examples/socrates.n3
 ```
 
+Run an eyelang program through the second engine:
+
+```bash
+eyeling --engine eyelang examples/eyelang/ancestor.pl
+```
+
+Or from JavaScript:
+
+```js
+const { reason } = require('eyeling');
+
+const output = reason({ engine: 'eyelang' }, `
+  materialize(out, 1).
+  in(done).
+  out(X) :- in(X).
+`);
+
+console.log(output);
+```
+
 ---
 
 ## Core concepts
@@ -533,7 +556,7 @@ The browser entry loads `dist/browser/eyeling.browser.js` and exposes the API th
 
 ## RDF-JS integration
 
-Eyeling includes a lightweight RDF-JS DataFactory and adapters for supported RDF-JS terms and quads.
+Eyeling includes a lightweight RDF-JS DataFactory and adapters for supported RDF-JS terms and quads. Its TypeScript declarations reuse the official `@rdfjs/types` interfaces, so Eyeling quads, terms, and data factories can be passed to other RDF-JS libraries without local type casts.
 
 ```js
 const { reasonStream, rdfjs } = require('eyeling');
@@ -558,12 +581,91 @@ const result = reasonStream(input, { rdfjs: true });
 console.log(result.closureQuads);
 ```
 
+TypeScript users can use Eyeling directly with `@rdfjs/types`:
+
+```ts
+import type { DataFactory, Quad } from '@rdfjs/types';
+import { rdfjs, reasonRdfJs } from 'eyeling';
+
+const ex = 'http://example.org/';
+const factory: DataFactory<Quad> = rdfjs;
+
+const facts: Quad[] = [
+  factory.quad(
+    factory.namedNode(`${ex}Socrates`),
+    factory.namedNode(`${ex}type`),
+    factory.namedNode(`${ex}Man`),
+  ),
+];
+
+for await (const quad of reasonRdfJs({
+  quads: facts,
+  n3: `
+    @prefix : <http://example.org/> .
+    { ?x :type :Man } => { ?x :type :Mortal } .
+  `,
+})) {
+  const derived: Quad = quad;
+  console.log(derived.subject.value, derived.predicate.value, derived.object.value);
+}
+```
+
+The built-in `rdfjs` factory implements the standard RDF-JS constructors for named nodes, blank nodes, literals, default graph terms, variables, and quads, plus `fromTerm()` and `fromQuad()` clone helpers. `@rdfjs/types` is installed with Eyeling because the public declarations import it.
+
 Supported RDF-JS input terms include named nodes, blank nodes, literals, variables, default graph terms, and default-graph quads. Named-graph input quads are rejected clearly unless handled through N3/TriG compatibility mode.
 
 Use RDF-JS when you want Eyeling to sit inside a JavaScript RDF pipeline. Use raw N3 input when you need N3-only features such as quoted formulas or N3 rules represented directly in source text.
 
 ---
 
+## Eyelang second engine
+
+Eyeling can also host the experimental `eyelang` engine. This is deliberately a second engine, not a rewrite of the N3 engine. The package therefore has two eyes:
+
+- the default **N3 engine** for RDF/Notation3 reasoning;
+- the **eyelang engine** for compact Prolog-style Horn clause programs.
+
+Use the CLI option when running `.pl` programs:
+
+```bash
+eyeling --engine eyelang examples/eyelang/ancestor.pl
+```
+
+Use the CommonJS convenience API when the rest of your application already imports `eyeling`:
+
+```js
+const { reason, reasonEyelang } = require('eyeling');
+
+const program = `
+  materialize(out, 1).
+  in(done).
+  out(X) :- in(X).
+`;
+
+console.log(reason({ engine: 'eyelang' }, program));
+console.log(await reasonEyelang(program));
+```
+
+Use the subpath export for the full eyelang module API:
+
+```js
+import { run, Program, Solver } from 'eyeling/eyelang';
+
+const result = run(program);
+console.log(result.stdout);
+```
+
+The two engines intentionally keep separate parsers, term models, solvers, and built-ins. Shared package entry points, examples, documentation, and CLI routing make them convenient to use together while keeping their execution models inspectable.
+
+Eyelang examples and language notes live under `examples/eyelang/`. The embedded engine runtime stays under `lib/eyelang/`, while the conformance corpus and test runners live under `test/eyelang/` so runtime code and test assets stay separate:
+
+```bash
+npm run test:eyelang        # integration check plus eyelang corpus
+npm run test:eyelang:corpus # eyelang corpus only
+```
+
+---
+
 ## RDF compatibility mode and RDF 1.2
 
 RDF compatibility mode is enabled with `--rdf` on the CLI or `{ rdf: true }` in the API.
@@ -694,17 +796,20 @@ Supported operations include:
 - `dt:sameValueAs` and `dt:differentValueFrom` for value-space equality and inequality;
 - `dt:canonicalLiteral` for canonical literal production.
 
-The built-ins use strict datatype lexical validation for these checks, including exact dateTime rollover/canonicalization such as `24:00:00` normalizing to the following day. They cover RDF language strings and the OWL 2 RL-relevant XSD set: `xsd:string`, `xsd:normalizedString`, `xsd:token`, `xsd:language`, `xsd:Name`, `xsd:NCName`, `xsd:NMTOKEN`, `xsd:boolean`, `xsd:decimal`, `xsd:integer` and its bounded integer subtypes, `xsd:float`, `xsd:double`, `xsd:hexBinary`, `xsd:base64Binary`, `xsd:anyURI`, `xsd:dateTime`, and `xsd:dateTimeStamp`.
+The built-ins use strict datatype lexical validation for these checks, including exact dateTime rollover/canonicalization such as `24:00:00` normalizing to the following day. They cover RDF language strings, `rdf:PlainLiteral`, `rdf:XMLLiteral`, `rdfs:Literal`, and the OWL 2 RL-relevant XSD set: `xsd:string`, `xsd:normalizedString`, `xsd:token`, `xsd:language`, `xsd:Name`, `xsd:NCName`, `xsd:NMTOKEN`, `xsd:boolean`, `xsd:decimal`, `xsd:integer` and its bounded integer subtypes, `xsd:float`, `xsd:double`, `xsd:hexBinary`, `xsd:base64Binary`, `xsd:anyURI`, `xsd:dateTime`, and `xsd:dateTimeStamp`. Lexical validation is intentionally strict for conformance: string-derived datatypes with whitespace-collapse facets must already be written in canonical collapsed lexical form, `xsd:float` and `xsd:double` enforce finite value ranges, `xsd:anyURI` rejects spaces, unsafe delimiters, and malformed percent escapes, and XML literals must be well-formed XML fragments.
 
 Example:
 
 ```n3
 @prefix : <http://example.org/> .
 @prefix dt: <https://eyereasoner.github.io/eyeling/datatype#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
 
 {
   "01"^^xsd:integer dt:sameValueAs "1.0"^^xsd:decimal .
+  "hello@EN"^^rdf:PlainLiteral dt:sameValueAs "hello@en"^^rdf:PlainLiteral .
+  "<a/>"^^rdf:XMLLiteral dt:validForDatatype rdf:XMLLiteral .
   "2026-06-10T12:00:00Z"^^xsd:dateTime
     dt:sameValueAs "2026-06-10T14:00:00+02:00"^^xsd:dateTime .
   ("abc"^^xsd:integer xsd:integer) dt:validForDatatype false .

package/bin/eyeling.cjs

@@ -1,10 +1,62 @@
 #!/usr/bin/env node
 'use strict';
 
-const bundle = require('../eyeling.js');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
 
-if (!bundle || typeof bundle.main !== 'function') {
-  throw new Error('Eyeling CLI bundle did not expose main()');
+function extractEngineArg(argv) {
+  const filtered = [];
+  let engine = null;
+  let endOptions = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (!endOptions && arg === '--') {
+      endOptions = true;
+      filtered.push(arg);
+    } else if (!endOptions && arg === '--engine') {
+      engine = argv[++i];
+      if (!engine) throw new Error('--engine needs a value');
+    } else if (!endOptions && arg.startsWith('--engine=')) {
+      engine = arg.slice('--engine='.length);
+    } else {
+      filtered.push(arg);
+    }
+  }
+
+  return { engine, argv: filtered };
 }
 
-bundle.main();
+function normalizeEngineName(value) {
+  if (value == null || value === '') return 'n3';
+  const name = String(value).toLowerCase();
+  if (name === 'n3' || name === 'eyeling') return 'n3';
+  if (name === 'eyelang' || name === 'prolog' || name === 'horn') return 'eyelang';
+  throw new Error(`unknown Eyeling engine: ${value}`);
+}
+
+async function runEyelangCli(argv) {
+  const cliUrl = pathToFileURL(path.join(__dirname, '..', 'lib', 'eyelang', 'cli.mjs')).href;
+  const cli = await import(cliUrl);
+  await cli.main(argv);
+}
+
+const parsed = extractEngineArg(process.argv.slice(2));
+const engine = normalizeEngineName(parsed.engine);
+
+if (engine === 'eyelang') {
+  runEyelangCli(parsed.argv).catch((error) => {
+    console.error(`eyeling: ${error && error.message ? error.message : String(error)}`);
+    process.exit(1);
+  });
+} else {
+  const bundle = require('../eyeling.js');
+
+  if (!bundle || typeof bundle.main !== 'function') {
+    throw new Error('Eyeling CLI bundle did not expose main()');
+  }
+
+  process.argv = [process.argv[0], process.argv[1], ...parsed.argv];
+  bundle.main();
+}

package/browser.d.ts

@@ -0,0 +1,63 @@
+export type EyelingPrefixEnv = import('eyeling').EyelingPrefixEnv;
+export type EyelingIri = import('eyeling').EyelingIri;
+export type EyelingLiteral = import('eyeling').EyelingLiteral;
+export type EyelingVar = import('eyeling').EyelingVar;
+export type EyelingBlank = import('eyeling').EyelingBlank;
+export type EyelingListTerm = import('eyeling').EyelingListTerm;
+export type EyelingOpenListTerm = import('eyeling').EyelingOpenListTerm;
+export type EyelingGraphTerm = import('eyeling').EyelingGraphTerm;
+export type EyelingTerm = import('eyeling').EyelingTerm;
+export type EyelingTriple = import('eyeling').EyelingTriple;
+export type EyelingRule = import('eyeling').EyelingRule;
+export type EyelingAstBundle = import('eyeling').EyelingAstBundle;
+export type N3Source = import('eyeling').N3Source;
+export type N3SourceListInput = import('eyeling').N3SourceListInput;
+export type RdfJsReasonInput = import('eyeling').RdfJsReasonInput;
+export type StoreOptions = import('eyeling').StoreOptions;
+export type BuiltinRegistrationContext = import('eyeling').BuiltinRegistrationContext;
+export type BuiltinHandler = import('eyeling').BuiltinHandler;
+export type ReasonStreamOptions = import('eyeling').ReasonStreamOptions;
+export type ReasonStreamResult = import('eyeling').ReasonStreamResult;
+export type FactStore = import('eyeling').FactStore;
+
+export function runAsync(
+  input: string | RdfJsReasonInput | EyelingAstBundle | N3SourceListInput,
+  opts?: ReasonStreamOptions,
+): Promise<ReasonStreamResult & { store?: FactStore }>;
+export function reasonStream(
+  input: string | RdfJsReasonInput | EyelingAstBundle | N3SourceListInput,
+  opts?: ReasonStreamOptions,
+): ReasonStreamResult;
+export function reasonRdfJs(
+  input: string | RdfJsReasonInput | EyelingAstBundle | N3SourceListInput,
+  opts?: Omit<ReasonStreamOptions, 'rdfjs' | 'onDerived'>,
+): AsyncIterable<import('@rdfjs/types').Quad>;
+
+export const INFERENCE_FUSE_EXIT_CODE: 65;
+export const rdfjs: import('eyeling').EyelingModule['rdfjs'];
+export function createFactStore(options?: string | StoreOptions | null): Promise<FactStore>;
+export function registerBuiltin(iri: string, handler: BuiltinHandler): BuiltinHandler;
+export function unregisterBuiltin(iri: string): boolean;
+export function registerBuiltinModule(mod: unknown, origin?: string): boolean;
+export function listBuiltinIris(): string[];
+export function collectOutputStringsFromFacts(facts: EyelingTriple[], prefixes: EyelingPrefixEnv): string[];
+export function prettyPrintQueryTriples(triples: EyelingTriple[], prefixes: EyelingPrefixEnv): string;
+
+export interface EyelingBrowserModule {
+  readonly version: string;
+  runAsync: typeof runAsync;
+  reasonStream: typeof reasonStream;
+  reasonRdfJs: typeof reasonRdfJs;
+  readonly INFERENCE_FUSE_EXIT_CODE: typeof INFERENCE_FUSE_EXIT_CODE;
+  rdfjs: typeof rdfjs;
+  createFactStore: typeof createFactStore;
+  registerBuiltin: typeof registerBuiltin;
+  unregisterBuiltin: typeof unregisterBuiltin;
+  registerBuiltinModule: typeof registerBuiltinModule;
+  listBuiltinIris: typeof listBuiltinIris;
+  collectOutputStringsFromFacts: typeof collectOutputStringsFromFacts;
+  prettyPrintQueryTriples: typeof prettyPrintQueryTriples;
+}
+
+declare const eyeling: EyelingBrowserModule;
+export default eyeling;