eyeling 1.8.1 → 1.8.3

package/README.md

@@ -117,7 +117,6 @@ Options:
   -a, --ast               Print parsed AST as JSON and exit.
   -e, --enforce-https     Rewrite http:// IRIs to https:// for log dereferencing builtins.
   -h, --help              Show this help and exit.
-  -n, --no-proof-comments Disable proof explanations (default).
   -p, --proof-comments    Enable proof explanations.
   -r, --strings           Print log:outputString strings (ordered by key) instead of N3 output.
   -s, --super-restricted  Disable all builtins except => and <=.
@@ -136,7 +135,7 @@ By default, `eyeling`:
 
 For each newly derived triple, `eyeling` prints:
 
-1. a proof-style comment block explaining why the triple holds (unless `-n`), and then
+1. a proof-style comment block explaining why the triple holds, and then
 2. the triple itself in N3/Turtle syntax.
 
 The proof comments are compact “local justifications” per derived triple (not a single exported global proof tree).

package/examples/odrl-policy-evaluation-snaf.n3

@@ -0,0 +1,242 @@
+# =============================================================================
+# ODRL Policies with scoped NAF via log:conclusion + log:(not)Includes
+#
+# Pattern:
+#   - Put "data + rules" in a quoted KB formula
+#   - Compute its deductive closure with log:conclusion
+#   - Ask questions about what the closure entails using log:includes / log:notIncludes
+#
+# What you get as output:
+#   - :decisionStatus  in { :PermitOnly, :DenyOnly, :Both, :Neither }
+#   - :effectiveDecision applying ODRL conflict strategy
+#
+# ODRL conflict strategies:
+#   odrl:perm      => Permission overrides Prohibition
+#   odrl:prohibit  => Prohibition overrides Permission
+#   odrl:invalid   => Conflicts void the whole policy
+# =============================================================================
+
+@prefix :    <http://example.org/odrl-paraconsistent#>.
+@prefix odrl: <http://www.w3.org/ns/odrl/2/>.
+@prefix log:  <http://www.w3.org/2000/10/swap/log#>.
+@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
+
+# ---------------------------------------------------------------
+# 1) KB formula: ODRL policies + requests + matching rules
+#    (kept inside a formula so raw derivations don’t clutter output)
+# ---------------------------------------------------------------
+
+:kb :hasFormula {
+
+  # ----------------------
+  # Assets / Parties
+  # ----------------------
+  :Report a odrl:Asset.
+  :Alice  a odrl:Party.
+  :Bob    a odrl:Party.
+
+  # ----------------------
+  # Policy Sets
+  # ----------------------
+
+  # Same rules, different conflict strategy:
+  :PS_Prohibit a odrl:Set; odrl:conflict odrl:prohibit.
+  :PS_Perm     a odrl:Set; odrl:conflict odrl:perm.
+  :PS_Invalid  a odrl:Set; odrl:conflict odrl:invalid.
+
+  # Rule templates (blank nodes are fine here)
+  # Permission: Alice may print Report for purpose Research
+  :PS_Prohibit odrl:permission [
+    odrl:target   :Report;
+    odrl:action   odrl:print;
+    odrl:assignee :Alice;
+    odrl:constraint [
+      odrl:leftOperand odrl:purpose;
+      odrl:operator    odrl:eq;
+      odrl:rightOperand :Research
+    ]
+  ].
+
+  :PS_Perm odrl:permission [
+    odrl:target   :Report;
+    odrl:action   odrl:print;
+    odrl:assignee :Alice;
+    odrl:constraint [
+      odrl:leftOperand odrl:purpose;
+      odrl:operator    odrl:eq;
+      odrl:rightOperand :Research
+    ]
+  ].
+
+  :PS_Invalid odrl:permission [
+    odrl:target   :Report;
+    odrl:action   odrl:print;
+    odrl:assignee :Alice;
+    odrl:constraint [
+      odrl:leftOperand odrl:purpose;
+      odrl:operator    odrl:eq;
+      odrl:rightOperand :Research
+    ]
+  ].
+
+  # Prohibition: Alice is prohibited to print Report (no constraint => always)
+  :PS_Prohibit odrl:prohibition [
+    odrl:target   :Report;
+    odrl:action   odrl:print;
+    odrl:assignee :Alice
+  ].
+
+  :PS_Perm odrl:prohibition [
+    odrl:target   :Report;
+    odrl:action   odrl:print;
+    odrl:assignee :Alice
+  ].
+
+  :PS_Invalid odrl:prohibition [
+    odrl:target   :Report;
+    odrl:action   odrl:print;
+    odrl:assignee :Alice
+  ].
+
+  # Extra: Bob may read (permit-only example)
+  :PS_Prohibit odrl:permission [
+    odrl:target   :Report;
+    odrl:action   odrl:read;
+    odrl:assignee :Bob
+  ].
+
+  # Extra: Bob is prohibited to distribute (deny-only example)
+  :PS_Prohibit odrl:prohibition [
+    odrl:target   :Report;
+    odrl:action   odrl:distribute;
+    odrl:assignee :Bob
+  ].
+
+  # ----------------------
+  # Requests we want to evaluate
+  # ----------------------
+
+  :Req_Alice_Print_Research_Prohibit
+    a :Request;
+    :policy   :PS_Prohibit;
+    :assignee :Alice;
+    :action   odrl:print;
+    :target   :Report;
+    :purpose  :Research.
+
+  :Req_Alice_Print_Research_Perm
+    a :Request;
+    :policy   :PS_Perm;
+    :assignee :Alice;
+    :action   odrl:print;
+    :target   :Report;
+    :purpose  :Research.
+
+  :Req_Alice_Print_Research_Invalid
+    a :Request;
+    :policy   :PS_Invalid;
+    :assignee :Alice;
+    :action   odrl:print;
+    :target   :Report;
+    :purpose  :Research.
+
+  :Req_Bob_Read
+    a :Request;
+    :policy   :PS_Prohibit;
+    :assignee :Bob;
+    :action   odrl:read;
+    :target   :Report.
+
+  :Req_Bob_Distribute
+    a :Request;
+    :policy   :PS_Prohibit;
+    :assignee :Bob;
+    :action   odrl:distribute;
+    :target   :Report.
+
+  :Req_Bob_Archive
+    a :Request;
+    :policy   :PS_Prohibit;
+    :assignee :Bob;
+    :action   odrl:archive;   # no rules mention this action => Neither
+    :target   :Report.
+
+  # ----------------------
+  # Decision derivation rules (inside KB)
+  # ----------------------
+
+  # Permission without constraint
+  { ?req a :Request; :policy ?ps; :assignee ?who; :action ?act; :target ?asset.
+    ?ps odrl:permission ?perm.
+    ?perm odrl:assignee ?who; odrl:action ?act; odrl:target ?asset.
+  } => { ?req :decision :Permit. }.
+
+  # Permission with purpose constraint (eq)
+  { ?req a :Request; :policy ?ps; :assignee ?who; :action ?act; :target ?asset; :purpose ?purpose.
+    ?ps odrl:permission ?perm.
+    ?perm odrl:assignee ?who; odrl:action ?act; odrl:target ?asset; odrl:constraint ?c.
+    ?c odrl:leftOperand odrl:purpose; odrl:operator odrl:eq; odrl:rightOperand ?purpose.
+  } => { ?req :decision :Permit. }.
+
+  # Prohibition without constraint
+  { ?req a :Request; :policy ?ps; :assignee ?who; :action ?act; :target ?asset.
+    ?ps odrl:prohibition ?proh.
+    ?proh odrl:assignee ?who; odrl:action ?act; odrl:target ?asset.
+  } => { ?req :decision :Deny. }.
+}.
+
+# ---------------------------------------------------------------
+# 2) Pull a few “queryable” facts out of the closure
+# ---------------------------------------------------------------
+
+{ :kb :hasFormula ?F. ?F log:conclusion ?C.
+  ?C log:includes { ?req :policy ?ps. ?ps odrl:conflict ?strategy. }.
+} => { ?req :conflictStrategy ?strategy. }.
+
+# ---------------------------------------------------------------
+# 3) DecisionStatus via scoped NAF on the closure
+# ---------------------------------------------------------------
+
+# Both (conflict)
+{ :kb :hasFormula ?F. ?F log:conclusion ?C.
+  ?C log:includes { ?req :decision :Permit. }.
+  ?C log:includes { ?req :decision :Deny. }.
+} => { ?req :decisionStatus :Both. }.
+
+# PermitOnly
+{ :kb :hasFormula ?F. ?F log:conclusion ?C.
+  ?C log:includes    { ?req :decision :Permit. }.
+  ?C log:notIncludes { ?req :decision :Deny. }.
+} => { ?req :decisionStatus :PermitOnly. }.
+
+# DenyOnly
+{ :kb :hasFormula ?F. ?F log:conclusion ?C.
+  ?C log:includes    { ?req :decision :Deny. }.
+  ?C log:notIncludes { ?req :decision :Permit. }.
+} => { ?req :decisionStatus :DenyOnly. }.
+
+# Neither (no applicable rules)
+{ :kb :hasFormula ?F. ?F log:conclusion ?C.
+  ?C log:notIncludes { ?req :decision :Permit. }.
+  ?C log:notIncludes { ?req :decision :Deny. }.
+} => { ?req :decisionStatus :Neither. }.
+
+# ---------------------------------------------------------------
+# 4) Effective decision applying ODRL conflict strategy
+# ---------------------------------------------------------------
+
+# Non-conflicts
+{ ?req :decisionStatus :PermitOnly. } => { ?req :effectiveDecision :Permit. }.
+{ ?req :decisionStatus :DenyOnly.   } => { ?req :effectiveDecision :Deny.   }.
+{ ?req :decisionStatus :Neither.    } => { ?req :effectiveDecision :NotSpecified. }.
+
+# Conflicts resolved by strategy + flag in the SAME derivation
+{ ?req :decisionStatus :Both. ?req :conflictStrategy odrl:prohibit. }
+  => { ?req :effectiveDecision :Deny;       :needsReview true. }.
+
+{ ?req :decisionStatus :Both. ?req :conflictStrategy odrl:perm. }
+  => { ?req :effectiveDecision :Permit;     :needsReview true. }.
+
+{ ?req :decisionStatus :Both. ?req :conflictStrategy odrl:invalid. }
+  => { ?req :effectiveDecision :VoidPolicy; :needsReview true. }.
+

package/examples/output/odrl-policy-evaluation-snaf.n3

@@ -0,0 +1,22 @@
+@prefix : <http://example.org/odrl-paraconsistent#> .
+@prefix odrl: <http://www.w3.org/ns/odrl/2/> .
+
+:Req_Alice_Print_Research_Prohibit :conflictStrategy odrl:prohibit .
+:Req_Alice_Print_Research_Perm :conflictStrategy odrl:perm .
+:Req_Alice_Print_Research_Invalid :conflictStrategy odrl:invalid .
+:Req_Bob_Read :conflictStrategy odrl:prohibit .
+:Req_Bob_Distribute :conflictStrategy odrl:prohibit .
+:Req_Bob_Archive :conflictStrategy odrl:prohibit .
+:Req_Alice_Print_Research_Prohibit :decisionStatus :Both .
+:Req_Alice_Print_Research_Perm :decisionStatus :Both .
+:Req_Alice_Print_Research_Invalid :decisionStatus :Both .
+:Req_Bob_Read :decisionStatus :PermitOnly .
+:Req_Bob_Distribute :decisionStatus :DenyOnly .
+:Req_Bob_Read :effectiveDecision :Permit .
+:Req_Bob_Distribute :effectiveDecision :Deny .
+:Req_Alice_Print_Research_Prohibit :effectiveDecision :Deny .
+:Req_Alice_Print_Research_Prohibit :needsReview true .
+:Req_Alice_Print_Research_Perm :effectiveDecision :Permit .
+:Req_Alice_Print_Research_Perm :needsReview true .
+:Req_Alice_Print_Research_Invalid :effectiveDecision :VoidPolicy .
+:Req_Alice_Print_Research_Invalid :needsReview true .

package/examples/output/paraconsistent-animals.n3

@@ -0,0 +1,38 @@
+@prefix : <http://example.org/paraconsistent#> .
+
+:tweety :canFlyStatus :Both .
+:mythic :canFlyStatus :Both .
+:falco :canFlyStatus :TrueOnly .
+:batsy :canFlyStatus :TrueOnly .
+:opus :canFlyStatus :FalseOnly .
+:batsy :hasWingsStatus :Both .
+:tweety :hasWingsStatus :TrueOnly .
+:falco :hasWingsStatus :TrueOnly .
+:mythic :hasWingsStatus :TrueOnly .
+:nemo :hasWingsStatus :FalseOnly .
+:tweety :inconsistent :canFly .
+:tweety :needsReview :canFly .
+:mythic :inconsistent :canFly .
+:mythic :needsReview :canFly .
+:batsy :inconsistent :hasWings .
+:batsy :needsReview :hasWings .
+:falco :canFlySafely true .
+:batsy :canFlySafely true .
+:opus :canFlySafely false .
+:tweety :canFlySafely :Undecided .
+:mythic :canFlySafely :Undecided .
+:tweety :hasWingsSafely true .
+:falco :hasWingsSafely true .
+:mythic :hasWingsSafely true .
+:nemo :hasWingsSafely false .
+:batsy :hasWingsSafely :Undecided .
+:falco :movesBySafely :Flying .
+:falco :migratesSafely true .
+:batsy :movesBySafely :Flying .
+:batsy :migratesSafely true .
+:opus :movesBySafely :Walking .
+:opus :migratesSafely false .
+:tweety :movesBySafely :Unknown .
+:tweety :migratesSafely :Undecided .
+:mythic :movesBySafely :Unknown .
+:mythic :migratesSafely :Undecided .

package/examples/paraconsistent-animals.n3

@@ -0,0 +1,109 @@
+# =============================================================================
+# Paraconsistent N3 example
+#
+# What it demonstrates:
+#   1) Contradictions tolerated: we can have both :p true and :p false.
+#   2) Scoped NAF via deductive closure:
+#        - compute closure with log:conclusion
+#        - check "absence" using log:notIncludes (scoped NAF)
+#        - check "presence" using log:includes
+#   3) Only meaningful derivations are materialized:
+#        - raw/possibly-contradictory facts are kept inside a quoted KB graph
+#        - we only output statuses + "safe" summaries
+# =============================================================================
+
+@prefix :    <http://example.org/paraconsistent#>.
+@prefix log: <http://www.w3.org/2000/10/swap/log#>.
+
+# ---------------------------------------------------------------
+# 1) Knowledge base (data + domain rules) stored as a graph term
+#    (so its internal derivations are not printed as top-level output)
+# ---------------------------------------------------------------
+
+:kb :hasFormula {
+
+  # --- Data (intentionally inconsistent in places) ---
+  :tweety  a :Bird, :Penguin.
+  :falco   a :Bird.
+  :opus    a :Penguin.
+  :batsy   a :Mammal, :Bat.
+  :nemo    a :Fish.
+
+  # explicit observation that conflicts with "Birds fly"
+  :mythic  a :Bird.
+  :mythic  :canFly false.
+
+  # --- Domain rules that may conflict ---
+  { ?x a :Bird.    } => { ?x :canFly true.  ?x :hasWings true. }.
+  { ?x a :Penguin. } => { ?x :canFly false. }.
+
+  { ?x a :Mammal.  } => { ?x :hasWings false. }.
+  { ?x a :Bat.     } => { ?x :hasWings true.  ?x :canFly true. }.
+
+  { ?x a :Fish.    } => { ?x :canSwim true.  ?x :hasWings false. }.
+}.
+
+# ---------------------------------------------------------------
+# 2) Status computation using:
+#      ?KB log:conclusion ?C .
+#      ?C  log:includes / log:notIncludes  { ... } .
+#
+# Status values: :TrueOnly / :FalseOnly / :Both
+# ---------------------------------------------------------------
+
+# Helper: get the closure once per match (no need to print it)
+{ :kb :hasFormula ?F. ?F log:conclusion ?C.
+  ?C log:includes { ?x :canFly true. }.
+  ?C log:includes { ?x :canFly false. }.
+} => { ?x :canFlyStatus :Both. }.
+
+{ :kb :hasFormula ?F. ?F log:conclusion ?C.
+  ?C log:includes    { ?x :canFly true. }.
+  ?C log:notIncludes { ?x :canFly false. }.
+} => { ?x :canFlyStatus :TrueOnly. }.
+
+{ :kb :hasFormula ?F. ?F log:conclusion ?C.
+  ?C log:includes    { ?x :canFly false. }.
+  ?C log:notIncludes { ?x :canFly true. }.
+} => { ?x :canFlyStatus :FalseOnly. }.
+
+
+{ :kb :hasFormula ?F. ?F log:conclusion ?C.
+  ?C log:includes { ?x :hasWings true. }.
+  ?C log:includes { ?x :hasWings false. }.
+} => { ?x :hasWingsStatus :Both. }.
+
+{ :kb :hasFormula ?F. ?F log:conclusion ?C.
+  ?C log:includes    { ?x :hasWings true. }.
+  ?C log:notIncludes { ?x :hasWings false. }.
+} => { ?x :hasWingsStatus :TrueOnly. }.
+
+{ :kb :hasFormula ?F. ?F log:conclusion ?C.
+  ?C log:includes    { ?x :hasWings false. }.
+  ?C log:notIncludes { ?x :hasWings true. }.
+} => { ?x :hasWingsStatus :FalseOnly. }.
+
+# ---------------------------------------------------------------
+# 3) Localize inconsistencies (paraconsistent: flag, don't explode)
+# ---------------------------------------------------------------
+
+{ ?x :canFlyStatus :Both. }    => { ?x :inconsistent :canFly.    ?x :needsReview :canFly. }.
+{ ?x :hasWingsStatus :Both. }  => { ?x :inconsistent :hasWings.  ?x :needsReview :hasWings. }.
+
+# ---------------------------------------------------------------
+# 4) Meaningful materialized summaries ("safe" single-valued views)
+# ---------------------------------------------------------------
+
+{ ?x :canFlyStatus :TrueOnly.  } => { ?x :canFlySafely true. }.
+{ ?x :canFlyStatus :FalseOnly. } => { ?x :canFlySafely false. }.
+{ ?x :canFlyStatus :Both.      } => { ?x :canFlySafely :Undecided. }.
+
+{ ?x :hasWingsStatus :TrueOnly.  } => { ?x :hasWingsSafely true. }.
+{ ?x :hasWingsStatus :FalseOnly. } => { ?x :hasWingsSafely false. }.
+{ ?x :hasWingsStatus :Both.      } => { ?x :hasWingsSafely :Undecided. }.
+
+# Safe behavior derived only from the safe canFlyStatus
+{ ?x :canFlyStatus :TrueOnly.  } => { ?x :movesBySafely :Flying.  ?x :migratesSafely true. }.
+{ ?x :canFlyStatus :FalseOnly. } => { ?x :movesBySafely :Walking. ?x :migratesSafely false. }.
+{ ?x :canFlyStatus :Both.      } => { ?x :movesBySafely :Unknown. ?x :migratesSafely :Undecided. }.
+

package/eyeling.js

@@ -7449,7 +7449,6 @@ function main() {
       `  -a, --ast               Print parsed AST as JSON and exit.\n` +
       `  -e, --enforce-https     Rewrite http:// IRIs to https:// for log dereferencing builtins.\n` +
       `  -h, --help              Show this help and exit.\n` +
-      `  -n, --no-proof-comments Disable proof explanations (default).\n` +
       `  -p, --proof-comments    Enable proof explanations.\n` +
       `  -r, --strings           Print log:outputString strings (ordered by key) instead of N3 output.\n` +
       `  -s, --super-restricted  Disable all builtins except => and <=.\n` +
@@ -7488,12 +7487,6 @@ function main() {
     proofCommentsEnabled = true;
   }
 
-  // --no-proof-comments / -n: disable proof explanations (default)
-  // Keep this after --proof-comments so -n wins if both are present.
-  if (argv.includes('--no-proof-comments') || argv.includes('-n')) {
-    proofCommentsEnabled = false;
-  }
-
   // --super-restricted / -s: disable all builtins except => / <=
   if (argv.includes('--super-restricted') || argv.includes('-s')) {
     superRestrictedMode = true;

package/index.d.ts

@@ -0,0 +1,3 @@
+declare module 'eyeling' {  
+    export function reason(opts:any,input: string): string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [
@@ -17,8 +17,10 @@
   "bin": {
     "eyeling": "./eyeling.js"
   },
+  "types": "./index.d.ts",
   "files": [
     "index.js",
+    "index.d.ts",
     "eyeling.js",
     "eyeling-builtins.ttl",
     "test",