# ==========================================================================
#  W03  Control through any number of shell companies
# ==========================================================================
#
#  FROM      Joining the Dots, "Assembling arguments"
#            https://www.semantechs.co.uk/articles/joining-the-dots/
#
#  DERIVES
#    The article's two rules. If A owns more than half of B, then A
#    controls B. If A controls B, and B controls C, then A controls C.
#    Then it checks the result: a company controlled by a sanctioned party
#    is flagged.
#
#  HOW IT WORKS
#    The article writes its rules in Datalog. Here they are SHACL-AF
#    rules, which the editor runs when the Inference dropdown says
#    "rules". inv:ControlRules holds two sh:SPARQLRule CONSTRUCTs. The
#    first turns each shareholding over 50% into inv:controls; the second
#    chains two inv:controls into a third. sh:order runs the first before
#    the second. One pass of the rules goes one step up the chain;
#    "rules, iterated" repeats them until nothing new turns up, which is
#    what the article means by following chains as far as they go.
#    inv:ControlProbe lists every inferred inv:controls as an Info result,
#    and inv:SanctionedControlShape warns about each company with a
#    sanctioned controller -- a simplified form of the US Treasury's 50
#    Percent Rule, which counts ownership rather than control.
#
#  DIAGRAM
#       Kestrel Trust --51%--> Northgate Nominees --60%--> Acme Holdings --75%--> Harbour Lettings
#                                                            |
#                                                            +--40%--> Blue Bay   (no control)
#
#       rule 1 (over 50%)       Kestrel>Northgate  Northgate>Acme  Acme>Harbour      3
#       rule 2, first pass      Kestrel>Acme       Northgate>Harbour                 2
#       rule 2, second pass     Kestrel>Harbour                                      1
#                                                                          total     6 info
#       sanctioned controller   Northgate, Acme, Harbour Lettings                    3 warnings
#
#  WHAT TO TAKE AWAY
#    - A rule adds statements; a shape then checks them like any others.
#    - Transitive rules need iterating. The specification defines one
#      pass; the editor's "rules, iterated" setting runs to a fixpoint.
#    - Every inferred statement can be traced to the rule and the
#      shareholdings that produced it: the explanation the article asks
#      for.
#
#  TRY IT
#    Set the Inference dropdown to "rules" (one pass) and validate again.
#    Five controls and two warnings: Kestrel's control of Harbour Lettings
#    is three steps away and one pass does not reach it.
#
#  DATA      investigation.ttl
#  INFERENCE rules-iterated   (the Inference dropdown in the editor)
#  LOAD IT   https://semantechs.co.uk/turtle-editor-viewer/?dot=https%3A%2F%2Fwww.semantechs.co.uk%2Farticles%2Fshow-your-working%2Fdemos%2F01-joining-the-dots%2Finvestigation.ttl&shapes=https%3A%2F%2Fwww.semantechs.co.uk%2Farticles%2Fshow-your-working%2Fdemos%2F01-joining-the-dots%2Fw03-control-through-the-shells.ttl&inference=rules-iterated
#  SPEC      SHACL-AF 8.6 SPARQL Rules; 8.2 sh:order
#            https://www.w3.org/TR/shacl-af/#SPARQLRule
#  REPORTS   does not conform -- 0 violations, 3 warnings, 6 info; 5 shapes
# ==========================================================================

@prefix inv:  <https://example.org/investigation/> .
@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix owl:  <http://www.w3.org/2002/07/owl#> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .

# Prefixes for the SPARQL inside this file. @prefix lines are Turtle syntax
# and do not reach the query engine; sh:declare does.
inv:prefixes
    a  owl:Ontology ;
    sh:declare [ sh:prefix "inv" ;  sh:namespace "https://example.org/investigation/"^^xsd:anyURI ] ;
    sh:declare [ sh:prefix "rdfs" ; sh:namespace "http://www.w3.org/2000/01/rdf-schema#"^^xsd:anyURI ] .

inv:ControlRules
    a              sh:NodeShape ;
    sh:targetClass inv:Shareholding ;
    sh:rule [
        a            sh:SPARQLRule ;
        sh:order     0 ;
        sh:prefixes  inv:prefixes ;
        sh:construct """
            CONSTRUCT { ?a inv:controls ?b }
            WHERE { $this inv:holder ?a ; inv:company ?b ; inv:percent ?p . FILTER (?p > 50) }
        """ ;
    ] ;
    sh:rule [
        a            sh:SPARQLRule ;
        sh:order     1 ;
        sh:prefixes  inv:prefixes ;
        sh:construct """
            CONSTRUCT { ?a inv:controls ?c }
            WHERE { $this inv:holder ?a . ?a inv:controls ?b . ?b inv:controls ?c . FILTER (?a != ?c) }
        """ ;
    ] .

inv:ControlProbe
    a              sh:NodeShape ;
    sh:targetSubjectsOf inv:controls ;
    sh:sparql [
        sh:prefixes  inv:prefixes ;
        sh:severity  sh:Info ;
        sh:message   "inferred: {?who} controls {?whom}" ;
        sh:select    """
            SELECT $this ?value ?who ?whom WHERE {
                $this inv:controls ?value .
                $this rdfs:label ?who . ?value rdfs:label ?whom .
            }
        """ ;
    ] .

inv:SanctionedControlShape
    a              sh:NodeShape ;
    sh:targetObjectsOf inv:controls ;
    sh:sparql [
        sh:prefixes  inv:prefixes ;
        sh:severity  sh:Warning ;
        sh:message   "{?company} is controlled by a sanctioned party, {?controller}." ;
        sh:select    """
            SELECT $this ?company ?controller WHERE {
                ?c inv:controls $this ; inv:sanctioned true .
                $this rdfs:label ?company . ?c rdfs:label ?controller .
            }
        """ ;
    ] .
