eyeling 1.13.6 → 1.14.0

package/HANDBOOK.md

@@ -1516,6 +1516,41 @@ A tiny `sprintf` subset:
 - Any other specifier (`%d`, `%f`, …) causes the builtin to fail.
 - Missing arguments are treated as empty strings.
 
+### Length and character utilities (Eyeling extensions)
+
+Eyeling also implements a few **non-standard** `string:` helpers that are handy for string-based algorithms. These are **not** part of the SWAP builtin set, so treat them as Eyeling extensions.
+
+#### `string:length`
+
+**Shape:** `s string:length n`
+
+Casts `s` to a string and returns its length as an integer literal token.
+
+#### `string:charAt`
+
+**Shape:** `( s i ) string:charAt ch`
+
+- `i` is a numeric term, truncated to an integer.
+- Indexing is **0-based** (like JavaScript).
+- If `i` is out of range, `ch` is the empty string `""`.
+
+#### `string:setCharAt`
+
+**Shape:** `( s i ch ) string:setCharAt out`
+
+Returns a copy of `s` with the character at index `i` (0-based) replaced by:
+
+- the **first character** of `ch` if `ch` is non-empty, otherwise
+- the empty string.
+
+If `i` is out of range, `out` is the original string.
+
+#### `string:hammingDistance`
+
+**Shape:** `( a b ) string:hammingDistance d`
+
+Returns the number of differing positions between `a` and `b`. Fails if the two strings have different lengths.
+
 ### Containment and prefix/suffix tests
 
 - `string:contains`
@@ -1941,6 +1976,24 @@ References:
 
 If you are running untrusted inputs, consider `--super-restricted` to disable all builtins except implication.
 
+### Eyeling fast-path builtins
+
+Eyeling ships one optional fast-path builtins builtin e.g. used by the genetic-algorithm example:
+
+#### `urn:eyeling:ga:solveString`
+
+**Shape:** `( target mutationProbability samples seed traceEvery maxGenerations ) urn:eyeling:ga:solveString ( generation score value seed )`
+
+- `target` and `value` are `xsd:string` literals.
+- `mutationProbability` is interpreted as a percentage per character (0–100).
+- `traceEvery` controls debug tracing:
+  - `0` disables tracing,
+  - `1` traces every generation,
+  - `N` traces every `N` generations.
+- `maxGenerations` is a safety cap:
+  - `0` means unlimited,
+  - otherwise the builtin stops once `generation >= maxGenerations` (even if not solved).
+
 ### A.6 Skolemization and `log:skolem`
 
 When forward rule heads contain blank nodes (existentials), Eyeling replaces them with generated Skolem IRIs so derived facts are ground.

package/README.md

@@ -2,9 +2,9 @@
 
 A compact [Notation3 (N3)](https://notation3.org/) reasoner in **JavaScript**.
 
-- Single self-contained bundle (`eyeling.js`), no external runtime deps
-- Forward (`=>`) + backward (`<=`) chaining over Horn-style rules
-- **CLI / npm `reason()` output is mode-dependent by default**: **newly derived forward facts** in normal mode, or — when top-level `{ ... } log:query { ... }.` directives are present — the **unique instantiated conclusion triples** of those queries (a forward-rule-like projection), optionally with compact proof comments
+- Single self-contained bundle (`eyeling.js`), no external runtime dependencies
+- Forward (`=>`) and backward (`<=`) chaining over Horn-style rules
+- **CLI / npm `reason()` output is mode-dependent by default**: it prints **newly derived forward facts** in normal mode, or (when top-level `{ ... } log:query { ... }.` directives are present) the **unique instantiated conclusion triples** of those queries, optionally with compact proof comments
 - Works in Node.js and fully client-side (browser/worker)
 
 ## Links
@@ -15,9 +15,7 @@ A compact [Notation3 (N3)](https://notation3.org/) reasoner in **JavaScript**.
 - **Notation3 test suite:** [https://codeberg.org/phochste/notation3tests](https://codeberg.org/phochste/notation3tests)
 - **Eyeling conformance report:** [https://codeberg.org/phochste/notation3tests/src/branch/main/reports/report.md](https://codeberg.org/phochste/notation3tests/src/branch/main/reports/report.md)
 
-Eyeling is regularly checked against the community Notation3 test suite; the report above tracks current pass/fail results.
-
-If you want to understand how the parser, unifier, proof search, skolemization, scoped closure, and builtins are implemented, start with the handbook.
+Eyeling is regularly checked against the community Notation3 test suite. If you want implementation details (parser, unifier, proof search, skolemization, scoped closure, builtins), start with the handbook.
 
 ## Quick start
 
@@ -31,7 +29,7 @@ If you want to understand how the parser, unifier, proof search, skolemization,
 npm i eyeling
 ```
 
-### CLI
+## CLI usage
 
 Run on a file:
 
@@ -39,23 +37,33 @@ Run on a file:
 npx eyeling examples/socrates.n3
 ```
 
-See all options:
+Show all options:
 
 ```bash
 npx eyeling --help
 ```
 
-### log:query output selection
+Useful flags include `--proof-comments`, `--stream`, `--strings`, and `--enforce-https`.
+
+## What gets printed?
+
+### Normal mode (default)
+
+Without top-level `log:query` directives, Eyeling prints **newly derived forward facts** by default.
+
+### `log:query` mode (output selection)
 
-If your input contains one or more **top-level** directives of the form:
+If the input contains one or more **top-level** directives of the form:
 
 ```n3
 { ?x a :Human. } log:query { ?x a :Mortal. }.
 ```
 
-Eyeling will still compute the saturated forward closure, but it will **print only** the **unique instantiated conclusion triples** of those `log:query` directives (instead of printing all newly derived forward facts).
+Eyeling still computes the saturated forward closure, but it **prints only** the **unique instantiated conclusion triples** of those `log:query` directives (instead of all newly derived forward facts).
 
-### JavaScript API
+## JavaScript API
+
+### npm helper: `reason()`
 
 CommonJS:
 
@@ -69,7 +77,7 @@ const input = `
 :Socrates a :Human.
 :Human rdfs:subClassOf :Mortal.
 
-{ ?S a ?A. ?A rdfs:subClassOf ?B } => { ?S a ?B }.
+{ ?s a ?A. ?A rdfs:subClassOf ?B. } => { ?s a ?B. }.
 `;
 
 console.log(reason({ proofComments: false }, input));
@@ -79,37 +87,57 @@ ESM:
 
 ```js
 import eyeling from 'eyeling';
+
 console.log(eyeling.reason({ proofComments: false }, input));
 ```
 
-Streaming / in-process reasoning (browser/worker, direct `eyeling.js`):
+Notes:
+
+- `reason()` returns the same textual output you would get from the CLI for the same input/options.
+- By default, the npm helper keeps output machine-friendly (`proofComments: false`).
+- The npm helper shells out to the bundled `eyeling.js` CLI for simplicity and robustness.
+
+### Direct bundle / browser-worker API: `reasonStream()`
+
+For in-process reasoning (browser, worker, or direct use of `eyeling.js`):
 
 ```js
-const { closureN3 } = eyeling.reasonStream(input, {
+const result = eyeling.reasonStream(input, {
   proof: false,
   onDerived: ({ triple }) => console.log(triple),
+  // includeInputFactsInClosure: false,
 });
 
-// `closureN3` is also mode-dependent:
-// - normal forward mode: closure (input facts + derived facts) by default
-// - `log:query` mode: the query-selected triples
-// To exclude input facts from the normal-mode closure, pass:
-//   includeInputFactsInClosure: false
-// The return value also includes `queryMode`, `queryTriples`, and `queryDerived`.
+console.log(result.closureN3);
 ```
 
-> Note: the npm `reason()` helper shells out to the bundled `eyeling.js` CLI for simplicity and robustness.
+#### `reasonStream()` output behavior
+
+`closureN3` is also mode-dependent:
+
+- **Normal mode:** by default, `closureN3` is the closure (**input facts + derived facts**)
+- **`log:query` mode:** `closureN3` is the **query-selected triples**
+
+To exclude input facts from the normal-mode closure, pass:
+
+```js
+includeInputFactsInClosure: false;
+```
+
+The returned object also includes `queryMode`, `queryTriples`, and `queryDerived` (and in normal mode, `onDerived` fires for newly derived facts; in `log:query` mode it fires for the query-selected derived triples).
 
 ## Builtins
 
-Builtins are defined in [eyeling-builtins.ttl](https://github.com/eyereasoner/eyeling/blob/main/eyeling-builtins.ttl) and described in the [HANDBOOK](https://eyereasoner.github.io/eyeling/HANDBOOK#ch11).
+Builtins are defined in [eyeling-builtins.ttl](https://github.com/eyereasoner/eyeling/blob/main/eyeling-builtins.ttl) and described in the [Handbook (Chapter 11)](https://eyereasoner.github.io/eyeling/HANDBOOK#ch11).
 
-## Testing (repo checkout)
+## Development and testing (repo checkout)
 
 ```bash
 npm test
 ```
 
+You can also inspect the `examples/` directory for many small and large N3 programs.
+
 ## License
 
-MIT (see [LICENSE](https://github.com/eyereasoner/eyeling/blob/main/LICENSE.md)).
+MIT — see [LICENSE.md](https://github.com/eyereasoner/eyeling/blob/main/LICENSE.md).

package/examples/genetic-algorithm.n3

@@ -0,0 +1,63 @@
+# ==========================================================================================
+# Genetic algorithm demo
+#
+# Genetic algorithm (GA) in a nutshell:
+# - Start with a random candidate string of the same length as the target.
+# - Repeatedly create a batch of “children” by copying the current best string and randomly
+#   mutating each character with a small probability.
+# - Score each child by how many positions differ from the target (Hamming distance).
+# - Keep the best-scoring child as the new current string and iterate until the score is 0.
+# This is a simple hill-climbing GA (selection + mutation, no crossover), using a seeded RNG
+# so runs are reproducible.
+#
+# Uses Eyeling's builtin:
+#   urn:eyeling:ga:solveString
+#
+# Configure:
+#   :mutationProbability 5   # percent per character
+#   :samples 80
+#   :seed 100
+#   :traceEvery 0            # 0=off, 1=every generation, 100=every 100 generations
+#   :maxGenerations 0        # 0=unlimited
+# ==========================================================================================
+
+@prefix :       <http://example.org/ga-solve#>.
+@prefix ega:    <urn:eyeling:ga:>.
+@prefix log:    <http://www.w3.org/2000/10/swap/log#>.
+@prefix string: <http://www.w3.org/2000/10/swap/string#>.
+
+:cfg
+  :mutationProbability 5;
+  :samples 80;
+  :seed 100;
+  :traceEvery 1;
+  :maxGenerations 0.
+
+# solveResult(TargetString) = (generation score value seed)
+{ ?TargetString :solveResult ( ?Gen ?Score ?Value ?Seed ) } <= {
+  :cfg :mutationProbability ?MutProb;
+       :samples ?Samples;
+       :seed ?Seed;
+       :traceEvery ?TraceEvery;
+       :maxGenerations ?MaxG.
+
+  ( ?TargetString ?MutProb ?Samples ?Seed ?TraceEvery ?MaxG )
+    ega:solveString
+  ( ?Gen ?Score ?Value ?SeedOut ) .
+
+  # By design, the 4th output is the (input) seed.
+  ?SeedOut log:equalTo ?Seed
+}.
+
+# Boolean-ish API for querying success
+{ ?TargetString :solved true } <= {
+  ?TargetString :solveResult ( ?Gen 0 ?TargetString ?Seed )
+}.
+
+# --------------------------------------------------------
+# Requested output: solve('METHINKS IT IS LIKE A WEASEL').
+# --------------------------------------------------------
+
+{ "METHINKS IT IS LIKE A WEASEL" :solved true .
+  ( "solve('%s').\n" "METHINKS IT IS LIKE A WEASEL" ) string:format ?Line
+} => { 1 log:outputString ?Line }.

package/examples/odrl-dpv-campaign-audit.n3

@@ -0,0 +1,195 @@
+# ===================================================================================
+# odrl-dpv-campaign-audit.n3
+#
+# A "reasoning about reasoning" example using both ODRL and DPV.
+#
+# What this demonstrates
+# ----------------------
+# 1) Object-level reasoning inside a quoted policy theory:
+#    - ODRL permissions specify who may read which dataset
+#    - DPV annotations specify policy purpose and data category
+#    - local rules translate ODRL + DPV metadata into effective access summaries
+#
+# 2) Meta-level reasoning outside that quoted theory:
+#    - compute the closure of the quoted policy theory
+#    - inspect what the policy theory entails
+#    - derive an audit decision based on those entailed consequences
+#
+# Why this is "reasoning about reasoning"
+# ---------------------------------------
+# The final audit decision is derived from statements ABOUT the closure of the quoted
+# policy theory (what the policy entails), not directly from the raw asserted policy.
+#
+# Modeling note
+# -------------
+# This is a pedagogical example:
+# - ODRL is used for policy structure (permission/assignee/target/action)
+# - DPV is used for privacy semantics (purpose, personal data categories)
+# - local rules map the combination into audit-friendly facts
+# ===================================================================================
+
+@prefix :     <http://example.org/#>.
+@prefix ey:   <https://eyereasoner.github.io/ns#>.
+@prefix odrl: <http://www.w3.org/ns/odrl/2/>.
+@prefix dpv:  <http://www.w3.org/ns/dpv#>.
+@prefix log:  <http://www.w3.org/2000/10/swap/log#>.
+
+# -----------------------------------------------
+# OBJECT THEORY (QUOTED ODRL + DPV POLICY THEORY)
+# -----------------------------------------------
+
+:case :policyTheory {
+  # ---- Request context (inside the quoted theory)
+  :ticket-99 :request :PublishCampaignAccessSummary.
+
+  # ---- Recipients (local classification for audit decisions)
+  :adVendor a :ExternalRecipient.
+  :marketingTeam a :InternalRecipient.
+
+  # ---- Datasets (annotated with DPV data category)
+  :AudienceList dpv:hasPersonalData dpv:PersonalData.
+  :ProductCatalog a :NonPersonalDataset.
+
+  # ---- ODRL policy A (benign-ish): internal team reads product catalog for service provision
+  :policy-internal a odrl:Set;
+    dpv:hasPurpose dpv:ServiceProvision;
+    odrl:permission [
+      odrl:assignee :marketingTeam;
+      odrl:target :ProductCatalog;
+      odrl:action odrl:read
+    ].
+
+  # ---- ODRL policy B (risky for publication): external vendor reads audience list for marketing
+  :policy-external a odrl:Set;
+    dpv:hasPurpose dpv:Marketing;
+    odrl:permission [
+      odrl:assignee :adVendor;
+      odrl:target :AudienceList;
+      odrl:action odrl:read
+    ].
+
+  # --------------------------------------------------------------------
+  # Object-level translation / normalization rules (pedagogical mapping)
+  # --------------------------------------------------------------------
+
+  # ODRL read permission -> effective read access
+  {
+    ?Policy odrl:permission [
+      odrl:assignee ?Recipient;
+      odrl:target ?Dataset;
+      odrl:action odrl:read
+    ].
+  }
+  =>
+  {
+    ?Recipient :canRead ?Dataset.
+  }.
+
+  # Lift policy purpose to the recipient (summary view used by the audit layer)
+  {
+    ?Policy dpv:hasPurpose ?Purpose.
+    ?Policy odrl:permission [
+      odrl:assignee ?Recipient;
+      odrl:target ?Dataset;
+      odrl:action odrl:read
+    ].
+  }
+  =>
+  {
+    ?Recipient :authorisedPurpose ?Purpose.
+  }.
+
+  # Combine ODRL permission target with DPV data-category annotation on the dataset
+  {
+    ?Policy odrl:permission [
+      odrl:assignee ?Recipient;
+      odrl:target ?Dataset;
+      odrl:action odrl:read
+    ].
+    ?Dataset dpv:hasPersonalData ?Category.
+  }
+  =>
+  {
+    ?Recipient :authorisedReadCategory ?Category.
+  }.
+}.
+
+# --------------------------
+# META-LEVEL POLICY ANALYSIS
+# --------------------------
+
+# 1) Compute the closure of the quoted ODRL+DPV policy theory.
+{
+  :case :policyTheory ?PolicyTheory.
+  ?PolicyTheory log:conclusion ?PolicyClosure.
+}
+=>
+{
+  :case :policyClosure ?PolicyClosure.
+}.
+
+# 2) Record a witness if the policy closure entails:
+#    external recipient + marketing purpose + personal-data access.
+#
+#    This is a statement ABOUT what the quoted theory entails.
+{
+  :case :policyClosure ?C.
+  ?C log:includes {
+    ?Recipient a :ExternalRecipient.
+    ?Recipient :authorisedPurpose dpv:Marketing.
+    ?Recipient :authorisedReadCategory dpv:PersonalData.
+  }.
+}
+=>
+{
+  :case :entails {
+    ?Recipient a :ExternalRecipient.
+    ?Recipient :authorisedPurpose dpv:Marketing.
+    ?Recipient :authorisedReadCategory dpv:PersonalData.
+  }.
+  :case :risk :ThirdPartyMarketingPersonalDataAccessEntailed.
+}.
+
+# 3) If the request is to publish the campaign access summary and the closure entails the
+#    risky pattern above, require manual review.
+{
+  :case :policyTheory ?PolicyTheory.
+  ?PolicyTheory log:includes {
+    :ticket-99 :request :PublishCampaignAccessSummary.
+  }.
+  :case :risk :ThirdPartyMarketingPersonalDataAccessEntailed.
+}
+=>
+{
+  :case :decision :ManualReviewRequired.
+}.
+
+# 4) Otherwise, if the same request is present but the closure does NOT entail any external
+#    recipient with marketing-purpose personal-data access, auto-approve.
+#
+#    Important: log:notIncludes applies to FORMULAS, so it is applied to ?C (the closure).
+{
+  :case :policyTheory ?PolicyTheory.
+  ?PolicyTheory log:includes {
+    :ticket-99 :request :PublishCampaignAccessSummary.
+  }.
+  :case :policyClosure ?C.
+  ?C log:notIncludes {
+    [] a :ExternalRecipient.
+    [] :authorisedPurpose dpv:Marketing.
+    [] :authorisedReadCategory dpv:PersonalData.
+  }.
+}
+=>
+{
+  :case :decision :AutoApprove.
+}.
+
+# ------------
+# QUERY INTENT
+# ------------
+
+# These top-level log:query directives define the query-projected outputs.
+{ :case :decision ?Decision. } log:query { :case :decision ?Decision. }.
+{ :case :entails ?Witness. }  log:query { :case :entails ?Witness. }.
+