eyeling 1.24.29 → 1.24.31

package/examples/odrl-benefits.n3

@@ -0,0 +1,221 @@
+# ======================================================================================
+# odrl-benefits.n3
+#
+# A very small example showing why ODRL policies are useful.
+#
+# The same machine-readable policy can:
+# - permit a good use case (medical research),
+# - block an unwanted use case (marketing),
+# - attach an operational duty (delete the data after use), and
+# - produce an explainable audit trail.
+# ======================================================================================
+
+@prefix :      <https://example.org/odrl-benefits#> .
+@prefix odrl:  <http://www.w3.org/ns/odrl/2/> .
+@prefix dct:   <http://purl.org/dc/terms/> .
+@prefix log:   <http://www.w3.org/2000/10/swap/log#> .
+@prefix string:<http://www.w3.org/2000/10/swap/string#> .
+@prefix xsd:   <http://www.w3.org/2001/XMLSchema#> .
+
+# -------------------
+# Parties and assets
+# -------------------
+
+:ResearchLab dct:title "Example Research Lab" .
+:HealthDataset dct:title "Pseudonymised health dataset" .
+:MedicalResearch dct:title "medical research" .
+:Marketing dct:title "marketing" .
+:Allowed dct:title "Allowed" .
+:Blocked dct:title "Blocked" .
+
+# -----------------------------
+# One compact ODRL policy
+# -----------------------------
+
+:Policy a odrl:Policy ;
+  dct:title "Health-data sharing policy" ;
+  odrl:permission :PermitResearchUse ;
+  odrl:prohibition :ProhibitMarketingUse .
+
+:PermitResearchUse a odrl:Permission ;
+  odrl:assignee :ResearchLab ;
+  odrl:target :HealthDataset ;
+  odrl:action odrl:use ;
+  odrl:constraint [
+    odrl:leftOperand odrl:purpose ;
+    odrl:operator odrl:eq ;
+    odrl:rightOperand :MedicalResearch
+  ] ;
+  odrl:duty :DeleteAfterUse .
+
+:DeleteAfterUse a odrl:Duty ;
+  odrl:action odrl:delete ;
+  odrl:target :HealthDataset ;
+  odrl:constraint [
+    odrl:leftOperand odrl:dateTime ;
+    odrl:operator odrl:lteq ;
+    odrl:rightOperand "2026-12-31"^^xsd:date
+  ] .
+
+:ProhibitMarketingUse a odrl:Prohibition ;
+  odrl:assignee :ResearchLab ;
+  odrl:target :HealthDataset ;
+  odrl:action odrl:use ;
+  odrl:constraint [
+    odrl:leftOperand odrl:purpose ;
+    odrl:operator odrl:eq ;
+    odrl:rightOperand :Marketing
+  ] .
+
+# -----------------
+# Two access requests
+# -----------------
+
+:RequestResearch a :Request ;
+  dct:title "Use the dataset for medical research" ;
+  odrl:assignee :ResearchLab ;
+  odrl:target :HealthDataset ;
+  odrl:action odrl:use ;
+  :purpose :MedicalResearch .
+
+:RequestMarketing a :Request ;
+  dct:title "Use the dataset for marketing" ;
+  odrl:assignee :ResearchLab ;
+  odrl:target :HealthDataset ;
+  odrl:action odrl:use ;
+  :purpose :Marketing .
+
+# ---------------------------
+# Minimal policy evaluation
+# ---------------------------
+
+# Benefit 1: permissions are machine-readable.
+{
+  ?request a :Request ;
+    odrl:assignee ?party ;
+    odrl:target ?asset ;
+    odrl:action ?action ;
+    :purpose ?purpose .
+
+  :Policy odrl:permission ?permission .
+  ?permission odrl:assignee ?party ;
+    odrl:target ?asset ;
+    odrl:action ?action ;
+    odrl:constraint [
+      odrl:leftOperand odrl:purpose ;
+      odrl:operator odrl:eq ;
+      odrl:rightOperand ?purpose
+    ] .
+}
+=>
+{
+  ?request :decision :Allowed ;
+    :benefit :MachineReadablePermission ;
+    :why "A matching ODRL permission grants this purpose-specific use." .
+} .
+
+# Benefit 2: prohibitions make unwanted use cases explicit.
+{
+  ?request a :Request ;
+    odrl:assignee ?party ;
+    odrl:target ?asset ;
+    odrl:action ?action ;
+    :purpose ?purpose .
+
+  :Policy odrl:prohibition ?prohibition .
+  ?prohibition odrl:assignee ?party ;
+    odrl:target ?asset ;
+    odrl:action ?action ;
+    odrl:constraint [
+      odrl:leftOperand odrl:purpose ;
+      odrl:operator odrl:eq ;
+      odrl:rightOperand ?purpose
+    ] .
+}
+=>
+{
+  ?request :decision :Blocked ;
+    :benefit :PurposeLimitation ;
+    :why "A matching ODRL prohibition blocks this purpose-specific use." .
+} .
+
+# Benefit 3: permitted use can carry operational duties.
+{
+  ?request :decision :Allowed ;
+    odrl:assignee ?party ;
+    odrl:target ?asset ;
+    odrl:action ?action ;
+    :purpose ?purpose .
+
+  :Policy odrl:permission ?permission .
+  ?permission odrl:assignee ?party ;
+    odrl:target ?asset ;
+    odrl:action ?action ;
+    odrl:constraint [
+      odrl:leftOperand odrl:purpose ;
+      odrl:operator odrl:eq ;
+      odrl:rightOperand ?purpose
+    ] ;
+    odrl:duty ?duty .
+
+  ?duty odrl:action odrl:delete ;
+    odrl:constraint [
+      odrl:leftOperand odrl:dateTime ;
+      odrl:operator odrl:lteq ;
+      odrl:rightOperand ?date
+    ] .
+}
+=>
+{
+  ?request :duty "Delete the dataset after the approved research use." ;
+    :deleteBy ?date ;
+    :benefit :OperationalDuty .
+} .
+
+# ----------------------------
+# Markdown report output
+# ----------------------------
+
+:out01 log:outputString "# odrl-benefits\n\n## Source files\n\n- [N3 rules](../odrl-benefits.n3)\n\n" .
+:out02 log:outputString "## Why ODRL helps\n\n" .
+:out03 log:outputString "This example uses one small ODRL policy to make data-use decisions explicit, machine-checkable, and auditable.\n\n" .
+:out04 log:outputString "### Policy in plain language\n\n" .
+:out05 log:outputString "- The research lab **may use** the pseudonymised health dataset for **medical research**.\n" .
+:out06 log:outputString "- The research lab **must delete** the dataset by `2026-12-31`.\n" .
+:out07 log:outputString "- The research lab **must not use** the dataset for **marketing**.\n\n" .
+:out08 log:outputString "### Evaluated requests\n\n" .
+:out09 log:outputString "| Request | Decision | Explanation |\n" .
+:out10 log:outputString "| --- | --- | --- |\n" .
+
+{
+  :RequestResearch dct:title ?title ;
+    :decision ?decision ;
+    :why ?why ;
+    :deleteBy ?date .
+  ?decision dct:title ?decisionLabel .
+
+  ("| %s | `%s` | %s Duty: delete by `%s`. |\n" ?title ?decisionLabel ?why ?date) string:format ?line .
+}
+=>
+{
+  :out11 log:outputString ?line .
+} .
+
+{
+  :RequestMarketing dct:title ?title ;
+    :decision ?decision ;
+    :why ?why .
+  ?decision dct:title ?decisionLabel .
+
+  ("| %s | `%s` | %s |\n" ?title ?decisionLabel ?why) string:format ?line .
+}
+=>
+{
+  :out12 log:outputString ?line .
+} .
+
+:out13 log:outputString "\n### Benefits illustrated\n\n" .
+:out14 log:outputString "1. **Clarity:** the policy says who may do what, to which asset, and for which purpose.\n" .
+:out15 log:outputString "2. **Automation:** requests can be allowed or blocked by rules instead of manual reading.\n" .
+:out16 log:outputString "3. **Purpose limitation:** research use and marketing use are treated differently.\n" .
+:out17 log:outputString "4. **Accountability:** duties such as deletion are part of the same policy and can be audited.\n" .

package/examples/output/odrl-benefits.md

@@ -0,0 +1,29 @@
+# odrl-benefits  
+
+## Source files  
+
+- [N3 rules](../odrl-benefits.n3)  
+
+## Why ODRL helps  
+
+This example uses one small ODRL policy to make data-use decisions explicit, machine-checkable, and auditable.  
+
+### Policy in plain language  
+
+- The research lab **may use** the pseudonymised health dataset for **medical research**.  
+- The research lab **must delete** the dataset by `2026-12-31`.  
+- The research lab **must not use** the dataset for **marketing**.  
+
+### Evaluated requests  
+
+| Request | Decision | Explanation |  
+| --- | --- | --- |  
+| Use the dataset for medical research | `Allowed` | A matching ODRL permission grants this purpose-specific use. Duty: delete by `2026-12-31`. |  
+| Use the dataset for marketing | `Blocked` | A matching ODRL prohibition blocks this purpose-specific use. |  
+
+### Benefits illustrated  
+
+1. **Clarity:** the policy says who may do what, to which asset, and for which purpose.  
+2. **Automation:** requests can be allowed or blocked by rules instead of manual reading.  
+3. **Purpose limitation:** research use and marketing use are treated differently.  
+4. **Accountability:** duties such as deletion are part of the same policy and can be audited.  

package/examples/output/rdf-message-flow.md

@@ -3,10 +3,10 @@
 ## Source files  
 
 - [N3 rules](../rdf-message-flow.n3)  
-- [Input TriG](../input/rdf-message-flow.trig)  
+- [Input RDF Message Log](../input/rdf-message-flow.trig)  
 
 ## Answer  
-Continuous RDF Message flow accepted: 5 ordered message envelopes moved through the ingest → validate → interpret → route → sink pipeline. The threshold was 26, so results 21 and 22 were archived, the heartbeat kept the stream alive, and results 28 and 29 were emitted as alerts.  
+Continuous RDF Message flow accepted: 5 ordered parser-replayed message envelopes moved through the ingest → validate → interpret → route → sink pipeline. The threshold was 26, so results 21 and 22 were archived, the empty heartbeat kept the stream alive, and results 28 and 29 were emitted as alerts.  
 
 ## Explanation  
-The input is a single runnable example split across an N3 rule file and a TriG sidecar. The TriG file uses example-local envelope facts for stream order and processing state, while each named payload graph is treated as an atomic RDF Message dataset. Only :m001 starts at ingress; each envelope must reach :sink before the continuous-flow rule releases its flow:nextEnvelope. Observation payloads are inspected with log:includes inside their own payload formula, and the empty heartbeat advances without a payload graph. This keeps message boundaries visible to the reasoner instead of merging all payload triples into one global graph.  
+The input sidecar is now a true RDF Message Log using VERSION \"1.2-messages\" and MESSAGE delimiters. Eyeling parses the log internally into an eymsg: replay view with ordered envelopes, offsets, next-envelope links, and one payload graph per non-empty message. Only the first replayed envelope starts at ingress; each envelope must reach :sink before the continuous-flow rule releases its eymsg:nextEnvelope. Observation payloads are inspected with log:includes inside their own message formula, and the delimiter-only third message is replayed as an empty heartbeat. This keeps message boundaries in the parser/runtime instead of modeling them by hand in the TriG sidecar.  

package/examples/rdf-message-flow.n3

@@ -9,28 +9,23 @@
 # Motivation
 # ----------
 # The RDF Messages draft describes an RDF Message as an RDF dataset interpreted
-# atomically, and an RDF Message Stream as an ordered sequence of such messages.
-# It also defines RDF Message Logs with explicit MESSAGE delimiters. This Eyeling
-# example keeps the same message-level discipline while staying in ordinary
-# N3/TriG that Eyeling can reason over today.
+# atomically, an RDF Message Stream as an ordered sequence of messages, and an
+# RDF Message Log as a static replayable representation of that stream.
 #
-# The companion TriG file therefore separates two layers:
+# The companion sidecar is now a true RDF Message Log: it uses
+# VERSION "1.2-messages" and MESSAGE delimiters. In RDF compatibility mode,
+# Eyeling parses those delimiters internally and materializes a replay view using
+# the eymsg: vocabulary: a stream resource, ordered envelopes, offsets,
+# next-envelope links, and one named payload graph per non-empty message.
 #
-#   1. example-local envelope facts in the default graph, such as order,
-#      processing stage, and payload graph; and
-#   2. one named graph per non-empty message payload, treated here as the RDF
-#      dataset/message that must be inspected atomically.
-#
-# The rules below deliberately do not merge all payload graphs into one global
-# graph. Instead, each observation is checked with log:includes inside the named
-# payload formula. The empty heartbeat has no payload graph but still advances
-# through the same pipeline. The next message is released only after the current
-# one reaches the sink, making the example a small back-pressure / flow-control
-# story rather than a batch merge of all input triples.
+# The rules below therefore no longer invent envelope facts in the TriG file.
+# They consume the replay view that Eyeling exposes, inspect each payload with
+# log:includes inside its own message formula, and let the empty heartbeat flow
+# through without a payload graph.
 
 @prefix : <https://eyereasoner.github.io/eyeling/examples/rdf-message-flow#>.
 @prefix flow: <https://eyereasoner.github.io/eyeling/examples/rdf-message-flow/vocab#>.
-@prefix prov: <http://www.w3.org/ns/prov#>.
+@prefix eymsg: <https://eyereasoner.github.io/eyeling/vocab/message#>.
 @prefix sosa: <http://www.w3.org/ns/sosa/>.
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
 @prefix math: <http://www.w3.org/2000/10/swap/math#>.
@@ -38,29 +33,49 @@
 @prefix log: <http://www.w3.org/2000/10/swap/log#>.
 @prefix string: <http://www.w3.org/2000/10/swap/string#>.
 
+# Eyeling's parser-level replay exposes the first envelope; that starts the
+# consumer-visible flow. Later envelopes are released only by the sink rule.
+{
+  ?Stream a eymsg:RDFMessageStream;
+    eymsg:firstEnvelope ?Envelope.
+} => {
+  ?Envelope :atStage :ingest.
+}.
+
+# Stream configuration is carried by the first RDF Message payload, not by a
+# hand-written sidecar envelope. The rule lifts only the threshold needed by the
+# routing rules into the ordinary reasoning context.
+{
+  ?Envelope eymsg:payloadGraph ?Payload.
+  ?Payload log:nameOf ?PayloadContext.
+  ?PayloadContext log:includes { :temperatureFlow :highThreshold ?Threshold. }.
+} => {
+  :temperatureFlow :highThreshold ?Threshold.
+}.
+
 # Stage 1: once an envelope has entered the stream, validate it.
 { ?Envelope :atStage :ingest. } => {
   ?Envelope :atStage :validate.
 }.
 
-# Stage 2: validation records that the envelope keeps an explicit message
-# boundary before the payload is interpreted.
+# Stage 2: validation records that the parser gave the reasoner an explicit
+# RDF Message boundary before the payload is interpreted.
 {
   ?Envelope :atStage :validate;
-    a flow:MessageEnvelope;
-    flow:offset ?Offset.
+    a eymsg:MessageEnvelope;
+    eymsg:offset ?Offset.
 } => {
   ?Envelope flow:boundaryExplicit true.
   ?Envelope :atStage :interpret.
 }.
 
-# Stage 3a: observation payloads are inspected inside their own payload graph.
-# This models the RDF Messages idea that messages are separate atomic datasets.
+# Stage 3a: observation payloads are inspected inside their own replayed message
+# graph. This keeps the RDF Messages default discipline: messages are atomic
+# datasets and are not silently merged.
 {
   ?Envelope :atStage :interpret;
-    flow:payloadKind :observation;
-    flow:expectedResult ?Result;
-    flow:payloadGraph ?Payload.
+    eymsg:payloadKind eymsg:nonEmpty;
+    eymsg:payloadGraph ?Payload.
   ?Payload log:nameOf ?PayloadContext.
   ?PayloadContext log:includes { ?Observation sosa:hasSimpleResult ?Result. }.
 } => {
@@ -69,10 +84,10 @@
 }.
 
 # Stage 3b: empty heartbeats contain no quads, but RDF Messages explicitly allow
-# empty messages, so the envelope still moves through the flow.
+# empty messages, so the parser-level envelope still moves through the flow.
 {
   ?Envelope :atStage :interpret;
-    flow:payloadKind :heartbeat.
+    eymsg:payloadKind eymsg:empty.
 } => {
   ?Envelope flow:emptyMessageAllowed true.
   ?Envelope :atStage :route.
@@ -112,46 +127,52 @@
   :heartbeatSink :received ?Envelope.
 }.
 
-# Continuous-flow rule: reaching the sink releases the next envelope into ingress.
-# This mirrors a consumer-visible ordered stream: later messages are not processed
-# until the earlier message has completed the pipeline.
+# Continuous-flow rule: reaching the sink releases the next replayed envelope
+# into ingress. The ordering link comes from Eyeling's internal MESSAGE replay,
+# not from the sidecar data.
 {
   ?Envelope :atStage :sink;
-    flow:nextEnvelope ?Next.
-  ?Next a flow:MessageEnvelope.
+    eymsg:nextEnvelope ?Next.
+  ?Next a eymsg:MessageEnvelope.
 } => {
   ?Envelope :releases ?Next.
   ?Next :atStage :ingest.
 }.
 
-# The Eyeling verdict is emitted only after all five envelopes have flowed
-# through ingest, validation, interpretation, routing, and sink while preserving
-# their message boundaries.
+# The verdict is emitted only after all five parser-replayed envelopes have
+# flowed through ingest, validation, interpretation, routing, and sink while
+# preserving message boundaries.
 {
-  :temperatureFlow flow:orderedEnvelopes ?Envelopes;
-    :highThreshold ?Threshold.
+  ?Stream a eymsg:RDFMessageStream;
+    eymsg:orderedEnvelopes ?Envelopes;
+    eymsg:firstEnvelope ?M1.
   ?Envelopes list:length ?Count.
-  :m001 :atStage :sink;
+  :temperatureFlow :highThreshold ?Threshold.
+  ?M1 :atStage :sink;
     flow:payloadResult ?FirstResult;
     :route :archiveSink;
-    :releases :m002.
-  :m002 :atStage :sink;
+    eymsg:nextEnvelope ?M2;
+    :releases ?M2.
+  ?M2 :atStage :sink;
     flow:payloadResult ?SecondResult;
     :route :archiveSink;
-    :releases :m003.
-  :m003 :atStage :sink;
+    eymsg:nextEnvelope ?M3;
+    :releases ?M3.
+  ?M3 :atStage :sink;
     flow:emptyMessageAllowed true;
     :route :heartbeatSink;
-    :releases :m004.
-  :m004 :atStage :sink;
+    eymsg:nextEnvelope ?M4;
+    :releases ?M4.
+  ?M4 :atStage :sink;
     flow:payloadResult ?FourthResult;
     :route :alertSink;
-    :releases :m005.
-  :m005 :atStage :sink;
+    eymsg:nextEnvelope ?M5;
+    :releases ?M5.
+  ?M5 :atStage :sink;
     flow:payloadResult ?FifthResult;
     :route :alertSink.
-  ("# rdf-message-flow\n\n## Source files\n\n- [N3 rules](../rdf-message-flow.n3)\n- [Input TriG](../input/rdf-message-flow.trig)\n\n## Answer\nContinuous RDF Message flow accepted: %d ordered message envelopes moved through the ingest → validate → interpret → route → sink pipeline. The threshold was %d, so results %s and %s were archived, the heartbeat kept the stream alive, and results %s and %s were emitted as alerts.\n\n## Explanation\nThe input is a single runnable example split across an N3 rule file and a TriG sidecar. The TriG file uses example-local envelope facts for stream order and processing state, while each named payload graph is treated as an atomic RDF Message dataset. Only :m001 starts at ingress; each envelope must reach :sink before the continuous-flow rule releases its flow:nextEnvelope. Observation payloads are inspected with log:includes inside their own payload formula, and the empty heartbeat advances without a payload graph. This keeps message boundaries visible to the reasoner instead of merging all payload triples into one global graph." ?Count ?Threshold ?FirstResult ?SecondResult ?FourthResult ?FifthResult) string:format ?Block.
+  ("# rdf-message-flow\n\n## Source files\n\n- [N3 rules](../rdf-message-flow.n3)\n- [Input RDF Message Log](../input/rdf-message-flow.trig)\n\n## Answer\nContinuous RDF Message flow accepted: %d ordered parser-replayed message envelopes moved through the ingest → validate → interpret → route → sink pipeline. The threshold was %d, so results %s and %s were archived, the empty heartbeat kept the stream alive, and results %s and %s were emitted as alerts.\n\n## Explanation\nThe input sidecar is now a true RDF Message Log using VERSION \\\"1.2-messages\\\" and MESSAGE delimiters. Eyeling parses the log internally into an eymsg: replay view with ordered envelopes, offsets, next-envelope links, and one payload graph per non-empty message. Only the first replayed envelope starts at ingress; each envelope must reach :sink before the continuous-flow rule releases its eymsg:nextEnvelope. Observation payloads are inspected with log:includes inside their own message formula, and the delimiter-only third message is replayed as an empty heartbeat. This keeps message boundaries in the parser/runtime instead of modeling them by hand in the TriG sidecar." ?Count ?Threshold ?FirstResult ?SecondResult ?FourthResult ?FifthResult) string:format ?Block.
 } => {
   :rdfMessageFlowExample log:outputString ?Block.
-  :rdfMessageFlowExample :demonstrates :ContinuousFlow, :BackPressureRelease, :AtomicMessageContext, :HeartbeatInFlow, :ThresholdRouting.
+  :rdfMessageFlowExample :demonstrates :ContinuousFlow, :BackPressureRelease, :AtomicMessageContext, :HeartbeatInFlow, :ThresholdRouting, :RDFMessageLogReplay.
 }.