eyeling 1.14.4 → 1.14.6

package/HANDBOOK.md

@@ -1549,12 +1549,6 @@ Returns a copy of `s` with the character at index `i` (0-based) replaced by:
 
 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`

package/examples/deck/schema-foaf-mapping.md

@@ -0,0 +1,219 @@
+# Mapping two data models (beginner-friendly)
+
+When people say “map two data models,” they mean:
+
+> **Taking data described using one vocabulary (Model A) and expressing the same meaning using another vocabulary (Model B).**
+
+In the Semantic Web / Linked Data world, a “data model” is often a **set of RDF terms** (classes + properties) defined by an ontology or vocabulary—like **schema.org** or **FOAF**.
+
+---
+
+## Why would you map vocabularies?
+
+Even if two vocabularies describe similar things, they may use **different names** and **different structures**.
+
+- **schema.org** is common for publishing data on the web (SEO, structured data).
+- **FOAF (Friend of a Friend)** is common for describing people, names, online accounts, and social relationships.
+
+Mapping lets you:
+
+- reuse tools built for another vocabulary,
+- integrate datasets that use different terms,
+- keep your original data but still answer queries in the target vocabulary.
+
+---
+
+## The core idea: “same meaning, different words”
+
+Example concept:
+
+- In **schema.org**, a person is `schema:Person`
+- In **FOAF**, a person is `foaf:Person`
+
+Those two classes can represent the same real-world thing (a person), just in different vocabularies.
+
+Similarly for properties:
+
+- `schema:name` ≈ `foaf:name`
+- `schema:givenName` ≈ `foaf:givenName`
+- `schema:familyName` ≈ `foaf:familyName`
+
+A mapping is just a **set of rules** that says:
+
+> “If you see X in schema.org, you can also produce Y in FOAF.”
+
+---
+
+## What is N3 (Notation3) and what are N3 rules?
+
+**N3** is a compact RDF syntax that also supports **rules**.
+
+A rule looks like:
+
+- **Left side (condition):** patterns you look for in your data
+- **Right side (conclusion):** triples you can _generate_ when the condition matches
+
+General shape:
+
+```n3
+{  # IF you find these triples...
+  ...patterns...
+}
+=>
+{  # THEN you may add these triples...
+  ...new triples...
+}.
+```
+
+This is sometimes called **forward-chaining**: you start with data you have, and rules _derive_ additional data.
+
+---
+
+## Example data in schema.org (RDF/Turtle)
+
+Imagine your dataset contains:
+
+```turtle
+@prefix schema: <https://schema.org/> .
+@prefix ex:     <https://example.org/> .
+
+ex:alice a schema:Person ;
+  schema:name "Alice Example" ;
+  schema:givenName "Alice" ;
+  schema:familyName "Example" .
+```
+
+This says:
+
+- `ex:alice` is a `schema:Person`
+- her full name is `"Alice Example"`
+- her given and family names are included too
+
+---
+
+## Mapping to FOAF using N3 rules
+
+Now we write rules that _derive_ FOAF triples.
+
+```n3
+@prefix schema: <https://schema.org/> .
+@prefix foaf:   <http://xmlns.com/foaf/0.1/> .
+
+# Rule 1: schema:Person -> foaf:Person
+{
+  ?p a schema:Person .
+}
+=>
+{
+  ?p a foaf:Person .
+}.
+
+# Rule 2: schema:name -> foaf:name
+{
+  ?p schema:name ?name .
+}
+=>
+{
+  ?p foaf:name ?name .
+}.
+
+# Rule 3: schema:givenName -> foaf:givenName
+{
+  ?p schema:givenName ?gn .
+}
+=>
+{
+  ?p foaf:givenName ?gn .
+}.
+
+# Rule 4: schema:familyName -> foaf:familyName
+{
+  ?p schema:familyName ?fn .
+}
+=>
+{
+  ?p foaf:familyName ?fn .
+}.
+```
+
+Read Rule 2 in plain English:
+
+> If a person `?p` has a `schema:name` value `?name`, then we can also say `?p` has a `foaf:name` value `?name`.
+
+---
+
+## What output do you get?
+
+After applying the rules, you still have your original schema.org data, **plus** extra FOAF triples like:
+
+```turtle
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+@prefix ex:   <https://example.org/> .
+
+ex:alice a foaf:Person ;
+  foaf:name "Alice Example" ;
+  foaf:givenName "Alice" ;
+  foaf:familyName "Example" .
+```
+
+So now FOAF-based tools or queries can work, even though your “source of truth” is schema.org.
+
+---
+
+## Important beginner notes
+
+### 1) Mapping usually _adds_ data (it doesn’t delete or replace)
+
+Most rule-based mappings are “non-destructive”:
+
+- Keep the original triples
+- Derive additional triples in the target vocabulary
+
+### 2) 1-to-1 mappings are the easy case
+
+`schema:name -> foaf:name` is straightforward.
+
+But sometimes:
+
+- one term in schema.org maps to **multiple** terms in FOAF, or
+- the target expects a different structure (blank nodes, split names, etc.)
+
+### 3) “Same meaning” is a judgment call
+
+Two properties might be _similar_ but not truly identical in all contexts. Mapping works best when you understand the intended meaning of each term.
+
+---
+
+## A simple mental checklist for mapping
+
+1. **List the things** you have (classes + properties in schema.org)
+2. **Decide what you want** to support (FOAF terms you need)
+3. For each target term, ask:
+   - “Where can I get this information from in the source?”
+
+4. Write rules:
+   - **conditions** match the source triples
+   - **conclusions** emit the target triples
+
+5. Run a reasoner/rule engine and test with a few example resources
+
+---
+
+## Next step ideas (optional)
+
+- Map online profiles:
+  - `schema:sameAs` could help populate `foaf:page` or related links (careful: semantics differ).
+
+- Add type rules beyond `Person`
+- Write rules that create structured nodes (more advanced)
+
+---
+
+## Summary
+
+Mapping two models is about **translating meaning across vocabularies**.
+
+- You start with data described in **schema.org**
+- You write **N3 rules** that recognize schema.org patterns
+- You **derive FOAF triples**
+- The result is data that can be consumed as if it were FOAF, without rewriting your original dataset

package/examples/genetic-algorithm-knapsack.n3

@@ -0,0 +1,260 @@
+# ================================================================================
+# Genetic Algorithm demo: 0/1 Knapsack via mutation + selection
+#
+# Goal
+# ----
+# Evolve a bitstring genome that selects a subset of items to maximize total VALUE
+# while staying within a WEIGHT capacity.
+#
+# Representation
+# --------------
+# - Items: list of pairs (weight value)
+# - Genome: a string of '0'/'1' of the same length as the item list
+#   - bit i = '1'  => item i is included
+#   - bit i = '0'  => item i is excluded
+#
+# Fitness (lower is better)
+# -------------------------
+# We want: feasible solutions (weight <= capacity) with high value.
+#
+#   If weight <= capacity:
+#       fitness = 1_000_000 - value        (so higher value => lower fitness)
+#   If overweight:
+#       fitness = 2_000_000 + (weight - capacity)
+#       (overweight candidates are always worse than any feasible candidate)
+#
+# Variation (mutation)
+# --------------------
+# Single-bit flip: generate all "neighbors" of the current genome by flipping
+# exactly one position. This is deterministic (no randomness), but it still
+# demonstrates the core GA pattern of mutation + selection.
+#
+# Selection
+# ---------
+# Compare parent + all mutants, keep the candidate with the lowest fitness.
+# This is essentially a (1 + λ) evolutionary strategy / hill-climber.
+#
+# Stopping criteria
+# -----------------
+# Stop when either:
+# - maxGenerations is reached, or
+# - no mutant improves fitness (local optimum under 1-bit flips)
+# ================================================================================
+
+@prefix :       <urn:ga:>.
+@prefix log:    <http://www.w3.org/2000/10/swap/log#>.
+@prefix math:   <http://www.w3.org/2000/10/swap/math#>.
+@prefix list:   <http://www.w3.org/2000/10/swap/list#>.
+@prefix string: <http://www.w3.org/2000/10/swap/string#>.
+
+:cfg
+  :capacity 50;
+  :maxGenerations 64;
+
+  # Each item is (weight value). Genome bits select items by index.
+  :items (
+    (12  24)
+    (7   13)
+    (11  23)
+    (8   15)
+    (9   16)
+    (6   12)
+    (10  21)
+    (4   9)
+    (5   11)
+    (14  28)
+    (3   7)
+    (13  26)
+  ).
+
+# -------------
+# small helpers
+# -------------
+
+{ ( ?N 1 ) :inc ?N1 } <= { ( ?N 1 ) math:sum ?N1 }.
+
+# build a string of N zeros
+{ ( 0 ) :zeros "" } <= true.
+
+{ ( ?N ) :zeros ?S } <= {
+  ?N math:greaterThan 0 .
+  ( ?N 1 ) math:difference ?N1 .
+  ( ?N1 ) :zeros ?Rest .
+  ( "%s%s" "0" ?Rest ) string:format ?S
+}.
+
+# flip a bit at index i in a 0/1 string
+{ ( ?S ?I ) :flipBit ?Out } <= {
+  ( ?S ?I ) string:charAt "0" .
+  ( ?S ?I "1" ) string:setCharAt ?Out
+}.
+
+{ ( ?S ?I ) :flipBit ?Out } <= {
+  ( ?S ?I ) string:charAt "1" .
+  ( ?S ?I "0" ) string:setCharAt ?Out
+}.
+
+# generate all single-bit mutants of S
+{ ( ?S ?Len ) :mutants ?Out } <= {
+  ( ?S 0 ?Len ) :mutantsFrom ?Out
+}.
+
+{ ( ?S ?I ?Len ) :mutantsFrom () } <= {
+  ?I math:equalTo ?Len
+}.
+
+{ ( ?S ?I ?Len ) :mutantsFrom ?Out } <= {
+  ?I math:lessThan ?Len .
+  ( ?S ?I ) :flipBit ?Cand .
+  ( ?I 1 ) :inc ?I1 .
+  ( ?S ?I1 ?Len ) :mutantsFrom ?Rest .
+  ( ( ?Cand ) ?Rest ) list:append ?Out
+}.
+
+# -----------------------------------------
+# decode genome -> (totalWeight totalValue)
+# -----------------------------------------
+
+{ ( ?Bits ?Items ) :totals ( ?Wsum ?Vsum ) } <= {
+  ?Bits string:length ?Len .
+  ( ?Bits ?Items 0 ?Len 0 0 ) :totalsAcc ( ?Wsum ?Vsum )
+}.
+
+{ ( ?Bits ?Items ?I ?Len ?AccW ?AccV ) :totalsAcc ( ?AccW ?AccV ) } <= {
+  ?I math:equalTo ?Len
+}.
+
+{ ( ?Bits ?Items ?I ?Len ?AccW ?AccV ) :totalsAcc ( ?Wsum ?Vsum ) } <= {
+  ?I math:lessThan ?Len .
+  ( ?Bits ?I ) string:charAt "1" .
+
+  ( ?Items ?I ) list:memberAt ?Pair .
+  ( ?Pair 0 ) list:memberAt ?W .
+  ( ?Pair 1 ) list:memberAt ?V .
+
+  ( ?AccW ?W ) math:sum ?AccW1 .
+  ( ?AccV ?V ) math:sum ?AccV1 .
+
+  ( ?I 1 ) :inc ?I1 .
+  ( ?Bits ?Items ?I1 ?Len ?AccW1 ?AccV1 ) :totalsAcc ( ?Wsum ?Vsum )
+}.
+
+{ ( ?Bits ?Items ?I ?Len ?AccW ?AccV ) :totalsAcc ( ?Wsum ?Vsum ) } <= {
+  ?I math:lessThan ?Len .
+  ( ?Bits ?I ) string:charAt "0" .
+
+  ( ?I 1 ) :inc ?I1 .
+  ( ?Bits ?Items ?I1 ?Len ?AccW ?AccV ) :totalsAcc ( ?Wsum ?Vsum )
+}.
+
+# -------------------------
+# fitness (lower is better)
+# -------------------------
+
+{ ( ?W ?V ?Cap ) :fitness ?F } <= {
+  ?W math:notGreaterThan ?Cap .
+  ( 1000000 ?V ) math:difference ?F
+}.
+
+{ ( ?W ?V ?Cap ) :fitness ?F } <= {
+  ?W math:greaterThan ?Cap .
+  ( ?W ?Cap ) math:difference ?Over .
+  ( 2000000 ?Over ) math:sum ?F
+}.
+
+{ ( ?W ?Cap ) :feasible "true" } <= { ?W math:notGreaterThan ?Cap }.
+{ ( ?W ?Cap ) :feasible "false" } <= { ?W math:greaterThan ?Cap }.
+
+{ ( ?Bits ?Cap ?Items ) :candidateScore ( ?Fit ?Wsum ?Vsum ) } <= {
+  ( ?Bits ?Items ) :totals ( ?Wsum ?Vsum ) .
+  ( ?Wsum ?Vsum ?Cap ) :fitness ?Fit
+}.
+
+# pick best of two candidates by fitness (ties keep the left candidate)
+{ ( ?C1 ?S1 ?W1 ?V1  ?C2 ?S2 ?W2 ?V2 ) :pickBest ( ?C1 ?S1 ?W1 ?V1 ) } <= {
+  ?S1 math:notGreaterThan ?S2
+}.
+
+{ ( ?C1 ?S1 ?W1 ?V1  ?C2 ?S2 ?W2 ?V2 ) :pickBest ( ?C2 ?S2 ?W2 ?V2 ) } <= {
+  ?S1 math:greaterThan ?S2
+}.
+
+# best candidate from a list
+{ ( ?Cap ?Items ?L ) :bestMutant ( ?Best ?BestScore ?BestW ?BestV ) } <= {
+  ?L list:length 1 .
+  ?L list:first ?Best .
+  ( ?Best ?Cap ?Items ) :candidateScore ( ?BestScore ?BestW ?BestV )
+}.
+
+{ ( ?Cap ?Items ?L ) :bestMutant ( ?Best ?BestScore ?BestW ?BestV ) } <= {
+  ?L list:length ?N .
+  ?N math:greaterThan 1 .
+
+  ?L list:first ?H .
+  ?L list:rest ?T .
+
+  ( ?Cap ?Items ?T ) :bestMutant ( ?B2 ?S2 ?W2 ?V2 ) .
+  ( ?H ?Cap ?Items ) :candidateScore ( ?S1 ?W1 ?V1 ) .
+
+  ( ?H ?S1 ?W1 ?V1  ?B2 ?S2 ?W2 ?V2 ) :pickBest ( ?Best ?BestScore ?BestW ?BestV )
+}.
+
+# --------------
+# evolution loop
+# --------------
+
+# generation cap
+{ ( ?Bits ?Cap ?Items ?Gen ?MaxGen ) :evolve ( ?Bits ?Gen ) } <= {
+  ?Gen math:equalTo ?MaxGen
+}.
+
+# stop if best doesn't improve
+{ ( ?Bits ?Cap ?Items ?Gen ?MaxGen ) :evolve ( ?Bits ?Gen ) } <= {
+  ?Gen math:lessThan ?MaxGen .
+  ( ?Bits ?Cap ?Items ) :candidateScore ( ?Score ?W ?V ) .
+
+  ?Bits string:length ?Len .
+  ( ?Bits ?Len ) :mutants ?Ms .
+  ( ( ?Bits ) ?Ms ) list:append ?Candidates .
+
+  ( ?Cap ?Items ?Candidates ) :bestMutant ( ?Best ?BestScore ?BW ?BV ) .
+  ?BestScore math:equalTo ?Score
+}.
+
+# keep evolving while improvement exists
+{ ( ?Bits ?Cap ?Items ?Gen ?MaxGen ) :evolve ( ?Final ?FinalGen ) } <= {
+  ?Gen math:lessThan ?MaxGen .
+  ( ?Bits ?Cap ?Items ) :candidateScore ( ?Score ?W ?V ) .
+
+  ?Bits string:length ?Len .
+  ( ?Bits ?Len ) :mutants ?Ms .
+  ( ( ?Bits ) ?Ms ) list:append ?Candidates .
+
+  ( ?Cap ?Items ?Candidates ) :bestMutant ( ?Best ?BestScore ?BW ?BV ) .
+  ?BestScore math:notEqualTo ?Score .
+
+  ( ?Gen 1 ) :inc ?Gen1 .
+  ( ?Best ?Cap ?Items ?Gen1 ?MaxGen ) :evolve ( ?Final ?FinalGen )
+}.
+
+# --------------
+# query / output
+# --------------
+
+{
+  :cfg :capacity ?Cap;
+       :maxGenerations ?Max;
+       :items ?Items.
+
+  ?Items list:length ?Len .
+  ( ?Len ) :zeros ?Start .
+
+  ( ?Start ?Cap ?Items 0 ?Max ) :evolve ( ?Best ?Gen ) .
+  ( ?Best ?Cap ?Items ) :candidateScore ( ?Fit ?W ?V ) .
+  ( ?W ?Cap ) :feasible ?Ok .
+
+  ( "Knapsack GA best genome %s (feasible=%s): weight=%s value=%s after %s generations.\n"
+    ?Best ?Ok ?W ?V ?Gen ) string:format ?Line
+}
+log:query
+{ 1 log:outputString ?Line }.

package/examples/n3-delegation-access.n3

@@ -0,0 +1,153 @@
+# ====================================================================
+# N3 LINKS POLICY, PROVENANCE, AND INFERENCE
+#
+# Another “speaks for itself” case:
+#   Delegation-based trust + distributed authorization.
+#
+# What it shows (in one syntax):
+#   - Quoted claims from multiple web documents
+#   - A tiny trust policy that can *delegate* trust to other documents
+#   - Importing only trusted statements into the fact set
+#   - Reasoning across imported facts to derive permissions
+#   - Provenance output using singleton graph terms (formulas),
+#     and *not stored* as derived facts.
+#
+# Run:
+#   eyeling examples/n3-delegation-access.n3
+#
+# Output:
+#   - :report :trusts <doc>
+#   - :report :entails { <user> :canRead <resource>. }
+#   - { ... } :assertedBy <doc>    (singleton graph provenance)
+# ====================================================================
+
+@prefix :     <https://example.org/n3-delegation#>.
+@prefix id:   <https://example.org/id/>.
+@prefix foaf: <http://xmlns.com/foaf/0.1/>.
+@prefix log:  <http://www.w3.org/2000/10/swap/log#>.
+
+# ----------
+# Trust root
+# ----------
+
+:policy :trusts <https://root.example/policy.n3>.
+
+# ------------------------------
+# The Web "says" (quoted graphs)
+# ------------------------------
+
+# Root policy delegates trust outward.
+<https://root.example/policy.n3> :says {
+  :policy :delegatesTo <https://hr.example/policy.n3>.
+  :policy :delegatesTo <https://team.example/members.n3>.
+}.
+
+# HR publishes what groups may read what.
+<https://hr.example/policy.n3> :says {
+  :eng :mayRead :buildReport.
+  :eng :mayRead :roadmap.
+}.
+
+# Team publishes membership, and delegates further.
+<https://team.example/members.n3> :says {
+  id:alice foaf:name "Alice".
+  id:alice :memberOf :eng.
+
+  :policy :delegatesTo <https://interns.example/members.n3>.
+}.
+
+# Intern list becomes trusted only because Team delegated to it.
+<https://interns.example/members.n3> :says {
+  id:eve foaf:name "Eve".
+  id:eve :memberOf :eng.
+}.
+
+# Untrusted rumor: present as quoted data, but will not be imported.
+<http://shady.example/rumor.n3> :says {
+  id:mallory foaf:name "Mallory".
+  id:mallory :memberOf :eng.
+  :eng :mayRead :secrets.
+}.
+
+# --------------------------------
+# Trust can be delegated (forward)
+# --------------------------------
+
+{
+  :policy :trusts ?Doc.
+  ?Doc :says ?F.
+  ?F log:includes { :policy :delegatesTo ?Other. }.
+}
+=>
+{
+  :policy :trusts ?Other.
+}.
+
+# ----------------------------------
+# Import only trusted quoted triples
+# ----------------------------------
+{
+  :policy :trusts ?Doc.
+  ?Doc :says ?F.
+  ?F log:includes { ?S ?P ?O. }.
+}
+=>
+{
+  ?S ?P ?O.
+}.
+
+# ------------------------------------------------
+# Local meaning: membership + policy => permission
+# ------------------------------------------------
+{
+  ?U :memberOf ?G.
+  ?G :mayRead ?R.
+}
+=>
+{
+  ?U :canRead ?R.
+}.
+
+# ------
+# REPORT
+# ------
+
+# Which documents ended up trusted (root + delegated)
+{
+  :policy :trusts ?Doc.
+}
+log:query
+{
+  :report :trusts ?Doc.
+}.
+
+# What the system entails
+{
+  ?U :canRead ?R.
+}
+log:query
+{
+  :report :entails { ?U :canRead ?R. }.
+}.
+
+# Why (provenance), using singleton graph terms:
+# show the two supporting asserted statements and where they came from.
+{
+  ?U :canRead ?R.
+
+  ?U :memberOf ?G.
+  ?G :mayRead ?R.
+
+  :policy :trusts ?DocM.
+  ?DocM :says ?FM.
+  ?FM log:includes { ?U :memberOf ?G. }.
+
+  :policy :trusts ?DocP.
+  ?DocP :says ?FP.
+  ?FP log:includes { ?G :mayRead ?R. }.
+}
+log:query
+{
+  { ?U :memberOf ?G. } :assertedBy ?DocM.
+  { ?G :mayRead ?R. }  :assertedBy ?DocP.
+}.