Règles de risque

Une règle de risque attribue un score à chaque objet d'un type cible — un navire, une société, une installation — et dit pourquoi. Chaque raison vérifiée ajoute son poids déclaré et cite les objets qui l'ont rendue vraie, de sorte que le score est exactement la somme des raisons listées. Aucun modèle n'intervient : les mêmes faits donnent toujours la même évaluation.

Chaque évaluation est écrite dans l'ontologie comme un objet dérivé d'un type que vous déclarez. Elle se lit comme n'importe quel autre objet, et un lecteur qui n'est pas habilité pour chacun des faits qui l'ont alimentée ne reçoit rien — pas une erreur.

Déclarer une règle de risque

Ajoutez un tableau riskRules à votre appel defineOntology :

import { defineOntology } from '@scrydon/sdk-authoring/ontologies'

export default defineOntology({
  id: 'maritime-picture',
  version: '1.0.0',
  displayName: 'Maritime picture',
  // ... object types (Vessel, PortCall, RiskAssessment, ...), link types, bindings, watch rules ...

  riskRules: [
    {
      slug: 'vessel-risk',
      displayName: 'Vessel risk',
      version: '1.0.0',
      target: { objectTypeSlug: 'Vessel' },

      reasons: [
        {
          id: 'flag-hopping',
          label: 'Flag changed twice in 12 months',
          weight: 20,
          evaluator: {
            kind: 'propertyChanges',
            viaLinkTypeSlug: 'SourceRecordOfVessel',
            property: 'flag',
            timeProperty: 'sourceAsOf',
            windowSeconds: 31_536_000,
            minChanges: 2,
          },
        },
        {
          id: 'sanctioned-port-call',
          label: 'Port call at a sanctioned terminal',
          weight: 30,
          evaluator: {
            kind: 'linkedPropertyIn',
            viaLinkTypeSlug: 'PortCallOfVessel',
            property: 'portLocode',
            values: ['IRBND'],
            where: { basis: 'observed' },
          },
        },
        {
          id: 'port-call-mismatch',
          label: 'Declared port calls disagree with what was observed',
          weight: 15,
          evaluator: {
            kind: 'declaredObservedMismatch',
            viaLinkTypeSlug: 'PortCallOfVessel',
            basisProperty: 'basis',
            declaredValue: 'declared',
            observedValue: 'observed',
            alignProperty: 'sequence',
            compareProperty: 'portLocode',
            timeProperty: 'arrivedAt',
          },
        },
        {
          id: 'ais-gap',
          label: 'AIS gap',
          weight: 25,
          evaluator: {
            kind: 'detectionWithin',
            objectTypeSlug: 'DarkVesselDetection',
            timeProperty: 'firedAt',
            windowSeconds: 86_400,
            evidenceProperty: 'evidence',
            evidenceKey: 'entityId',
            subjectProperty: 'mmsi',
          },
        },
      ],

      // The same vessel scores higher inside a zone of interest.
      context: {
        area: { objectTypeSlug: 'ZoneOfInterest', areaIds: ['be-eez'] },
        position: { latProperty: 'lastLatitude', lngProperty: 'lastLongitude' },
        multiplier: 1.5,
      },

      // Which sources may feed the score (a filter, see below).
      sources: { property: 'sourceSystem', allow: ['LLOYDS', 'GISIS', 'EMSA'], unattributed: 'include' },

      freshness: { maxAgeSeconds: 604_800 },

      bands: [
        { name: 'low', minScore: 0 },
        { name: 'elevated', minScore: 30 },
        { name: 'high', minScore: 60 },
      ],

      emit: {
        objectTypeSlug: 'RiskAssessment',
        clearanceCeiling: { schemeId: 'default', rank: 2 },
      },
    },
  ],
})

Référence des champs

Chaque type d'objet et type de lien nommé par une règle doit être déclaré dans la même ontologie, et chaque lien qu'une raison parcourt doit toucher le type cible. Une règle qui nomme un élément absent échoue à l'installation.

Évaluateurs

L'ensemble des évaluateurs est fermé. Chacun lit les objets liés à la cible (viaLinkTypeSlug) ou les détections d'un type, et est vérifié lorsque sa condition est remplie.

Un type de lien déclaré avec une join et sans liaison de lien est lu par sa jointure : les objets liés sont ceux de l'autre type dont la colonne de jointure est égale à celle de la cible. Une jointure avec normalize ou une extrémité "*" ne peut pas être lue ainsi ; une cible qui en dépend est signalée incomplete-read au lieu d'être notée.

Chaque raison cite au plus 16 objets. Tout fait lu par la règle compte quand même dans le marquage de l'évaluation, cité ou non.

Lecture des objets liés

Une raison dotée d'une fenêtre (propertyChanges, ou linkedPropertyIn avec timeProperty + windowSeconds) ne lit que les objets liés que son timeProperty date dans windowSeconds : une cible au long historique — un navire aux milliers de positions AIS — est lue une fenêtre à la fois. Les objets liés hors de toute fenêtre n'alimentent ni l'évaluation ni son marquage. Une lecture de liens renvoie au plus 500 objets, et une lecture de détections au plus 200 par type de détection. Lorsqu'une lecture s'arrête à cette limite, la cible est quand même évaluée si les objets lus tranchent la raison :

La fenêtre n'est appliquée par la lecture que pour un lien déclaré avec une join et sans liaison de lien. Un lien doté d'une liaison de lien est lu en entier, et la même règle tranche lorsque plus de 500 objets l'arrêtent.

Contexte

context.position place la cible soit par ses propres latProperty / lngProperty, soit — avec viaLinkTypeSlug et timeProperty — par le dernier objet lié qui n'est pas plus ancien que freshness.maxAgeSeconds. Seul ce dernier objet est lu : l'évaluation remonte depuis l'instant présent, en doublant à partir d'une minute, et ne lit donc jamais un long historique pour le trouver. Les zones sont des lignes de context.area.objectTypeSlug portant un areaId et une boîte minLatitude / maxLatitude / minLongitude / maxLongitude, la même forme de ligne qu'une règle de surveillance lit. Lorsque la cible se trouve dans l'une d'elles, la contribution de chaque raison est multipliée par multiplier.

Liste des sources autorisées

sources décide quels faits peuvent alimenter le score, selon la valeur de sources.property sur chaque fait. Un fait provenant d'une source absente de allow est exclu du score et du marquage. unattributed indique le sort d'un fait qui ne nomme aucune source (une détection, une ligne de zone) : include ou exclude.

L'évaluation

Chaque évaluation est un objet du type emit, une par (règle, objet cible). Une nouvelle évaluation remplace la précédente pour la même cible, il y a donc toujours exactement une évaluation en vigueur.

Marquage. Une évaluation est marquée à la jointure de tous les faits qui l'ont alimentée et de la règle elle-même, jamais au-dessus de emit.clearanceCeiling, et jamais en dessous de l'évaluation qu'elle remplace. Un lecteur habilité pour tout cela la lit ; tout autre lecteur ne reçoit aucun objet.

Lancer une évaluation

Les évaluations sont produites lorsqu'une évaluation est lancée, et seulement alors : risk.assess ne peut pas être soumise via actions.submit, de sorte que chaque évaluation a été dérivée par une évaluation lancée.

La plateforme lance une évaluation pour chaque environnement d'espace de travail selon la même planification que les règles de surveillance, juste après les surveillances de cet environnement, afin qu'une raison detectionWithin voie les détections produites par ce passage. Elle s'exécute sous le compte d'exécution des surveillances de l'environnement, avec les mêmes effets : sans compte sélectionné, seules les règles dont le plafond est de rang 0 sont évaluées ; avec un compte, une règle dont le plafond dépasse le rang d'habilitation du compte est ignorée ; avec un compte qui ne remplit plus les conditions, aucune règle n'est évaluée et aucune ne se rabat sur l'identité de la plateforme. Une règle ignorée pour habilitation figure avec sa raison dans les résultats d'une évaluation à la demande ; le passage planifié ne la journalise pas.

Pour évaluer à la demande, appelez-la depuis le SDK d'ontologie :

const result = await ontology.riskAssessments.evaluate({ ontology: 'maritime-picture' })
// { evaluated, assessed, degradedReads, outcomes: [{ ruleName, objectId, assessed, reason?, assessmentId?, marking? }] }

L'évaluation lit au emit.clearanceCeiling de chaque règle et ignore une règle dont votre habilitation n'atteint pas le plafond. Une évaluation identique à celle en vigueur n'est pas réécrite (reason: "unchanged"). Une cible dont les faits n'ont pas pu être lus entièrement n'est pas évaluée (reason: "incomplete-read") plutôt que de recevoir un score bas.