eyeling 1.26.6 → 1.27.0

package/examples/deck/rdf-message-cold-chain-recall.md

@@ -0,0 +1,71 @@
+# RDF Message Cold Chain Recall
+
+This deck follows a cold-chain stream where the cost of a wrong conclusion is concrete: either release a shipment or quarantine it. The [rules](../rdf-message-cold-chain-recall.n3) replay the LDES [message log input](../input/rdf-message-cold-chain-recall.trig), the [golden output](../output/rdf-message-cold-chain-recall.md) records the repaired decision, and the [handbook section](https://eyereasoner.github.io/eyeling/HANDBOOK#rdf-message-log-replay-under--r) explains how `-r` exposes RDF Message boundaries to the rules.
+
+## Why this example exists
+
+A cold-chain monitor receives a long telemetry stream for a medicine batch.
+
+Most readings are old and already materialized.  The consumer has a checkpoint, so reloading and rechecking the whole stream would be wasteful.  But the new tail is not clean: one message says the batch remained in range, while another says it crossed the temperature limit.
+
+The example shows why streaming RDF reasoning needs three things together:
+
+1. message boundaries, so the rules know which facts arrived together;
+2. LDES sequence metadata, so the consumer resumes after a checkpoint;
+3. a repair policy, so contradictory tail evidence is fixed before an operational decision is emitted.
+
+## The story
+
+`batchA` is moving through a cold-chain route.
+
+The stream contains forty-eight telemetry observations.  The first forty-two were already processed in an earlier synchronization run:
+
+```turtle
+:telemetryStream :lastCommittedSequence 42 .
+```
+
+That leaves only messages `43..48` for the current incremental repair window.
+
+## The contradiction
+
+The new tail contains both kinds of evidence:
+
+```turtle
+:obs-043 :temperatureTenthC 45 .   # 4.5°C, within range
+:obs-047 :temperatureTenthC 118 .  # 11.8°C, over the 8.0°C limit
+```
+
+Flattening the tail would make the batch look both safe and unsafe.
+
+## The repair
+
+The repair policy is intentionally simple and auditable: for recall decisions, a calibrated cold-chain logger wins over lower-priority telemetry.
+
+```turtle
+:obs-047 :source "calibrated-cold-chain-logger" ;
+  :priority 5 ;
+  :calibrationClass :calibratedLogger .
+```
+
+Because that repaired reading is over the limit, the materialized decision is:
+
+> quarantine batchA, notify QA, and hold shipment
+
+## Why this is a good streaming case
+
+The example is not about proving that one temperature number is bigger than another.
+
+It is about the shape of the pipeline:
+
+- the stream can keep growing;
+- the consumer can resume from a bookmark;
+- old messages do not need to be reprocessed;
+- the inconsistent new tail is repaired locally;
+- the final output is based on the repaired state, not on the raw noisy merge.
+
+## Run it
+
+```bash
+eyeling -r examples/rdf-message-cold-chain-recall.n3 \
+  examples/input/rdf-message-cold-chain-recall.trig
+```

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

@@ -1,6 +1,6 @@
 # RDF Message Logs in Eyeling — from stream to reasoning
 
-This deck explains the example `rdf-message-flow.n3` and its input file `input/rdf-message-flow.trig`.
+This deck reads alongside the [rules](../rdf-message-flow.n3) and the replayed [message log input](../input/rdf-message-flow.trig): the [golden output](../output/rdf-message-flow.md) shows what Eyeling derives once `-r` has exposed the RDF Message envelopes and payload graphs. The [handbook section](https://eyereasoner.github.io/eyeling/HANDBOOK#rdf-message-log-replay-under--r) explains that replay step in more detail.
 
 The goal is to show, in plain language, how Eyeling can now read an RDF Message Log directly instead of asking the example data to describe its own message envelopes by hand.
 

package/examples/deck/rdf-message-ldes-incremental.md

@@ -0,0 +1,94 @@
+# RDF Message LDES Incremental Repair
+
+This deck walks through a stream that is large enough to make full recomputation unattractive. The [rules](../rdf-message-ldes-incremental.n3) consume the replayed LDES [message log input](../input/rdf-message-ldes-incremental.trig), the [golden output](../output/rdf-message-ldes-incremental.md) shows the incremental repair result, and the [handbook section](https://eyereasoner.github.io/eyeling/HANDBOOK#rdf-message-log-replay-under--r) explains how `-r` turns RDF Message boundaries into facts for the rules.
+
+## Why this example exists
+
+A long-running stream should not force a reasoner to reload and re-check all past data every time a new event arrives.
+
+This example shows the intended shape:
+
+1. publish events as an append-only **LDES**;
+2. serialize each emitted member as an **RDF Message**;
+3. remember a sequence bookmark from the previous synchronization run;
+4. reason only over the new tail;
+5. repair a noisy inconsistency before materializing the operational result.
+
+## The story
+
+A building monitors a fire door, `doorA`.
+
+The stream contains forty door observations.  Most are boring historical facts that were already processed.  The consumer has stored this checkpoint:
+
+```turtle
+:doorStream :lastCommittedSequence 34 .
+```
+
+So when the log is replayed, the reasoner can classify:
+
+- sequences `1..34` as committed history;
+- sequences `35..40` as newly emitted LDES members;
+- the new tail as the current repair window.
+
+## Why RDF Messages help
+
+The input file is a real RDF Message Log:
+
+```turtle
+VERSION "1.2-messages"
+...
+MESSAGE
+...
+MESSAGE
+...
+```
+
+Eyeling's `-r` mode preserves those message boundaries as `eymsg:` envelopes and payload graphs.  The rules inspect payloads with `log:includes`, so each member remains scoped to the message that emitted it.
+
+Handbook: <https://eyereasoner.github.io/eyeling/HANDBOOK#rdf-message-log-replay-under--r>
+
+## Why LDES helps
+
+LDES contributes the stream shape:
+
+```turtle
+:doorStream a ldes:EventStream ;
+  ldes:timestampPath :observedAt ;
+  ldes:sequencePath :sequence ;
+  tree:member :obs-040 .
+```
+
+The stream is append-only, and each member has a sequence number.  That sequence number is the incremental bookmark: a consumer that already committed `34` does not need to re-run the repair over members `1..34`.
+
+LDES spec: <https://semiceu.github.io/LinkedDataEventStreams/releases/1.0.0-alpha/index.html>
+
+## The inconsistency
+
+The new tail contains contradictory evidence:
+
+- the camera says `doorA` is `:open`;
+- the latch says `doorA` is `:closed`;
+- the safety controller also says `doorA` is `:closed`, with higher priority.
+
+Raw materialization would say the same door is both open and closed.
+
+## The repair
+
+The preferred repair keeps the highest-priority tail assertion:
+
+```turtle
+:obs-040 :doorState :closed ;
+  :priority 5 ;
+  :source "safety-controller" .
+```
+
+The materialized action is therefore:
+
+> keep the compartment sealed and continue monitoring
+
+## Run it
+
+```bash
+eyeling -r examples/rdf-message-ldes-incremental.n3 \
+  examples/input/rdf-message-ldes-incremental.trig
+```

package/examples/deck/rdf-message-window-repair.md

@@ -0,0 +1,175 @@
+# RDF Message window repair — fixing an open/closed door conflict
+
+This deck follows a small RDF Message window where one door is reported both open and closed. The [rules](../rdf-message-window-repair.n3) inspect the replayed [message log input](../input/rdf-message-window-repair.trig), the [golden output](../output/rdf-message-window-repair.md) shows the repaired conclusion, and the [handbook section](https://eyereasoner.github.io/eyeling/HANDBOOK#rdf-message-log-replay-under--r) explains how `-r` exposes message payloads without silently merging them.
+
+The goal is to show how Eyeling can reason over a replayed RDF Message Log, keep message boundaries visible, detect an inconsistency in a sliding window, and materialize a repaired conclusion instead of blindly merging contradictory facts.
+
+---
+
+## The story
+
+A building automation system receives RDF messages about a fire door.
+
+The messages arrive from different devices:
+
+- a corridor camera,
+- a hallway latch sensor,
+- and a safety controller.
+
+Most of the time they agree. But in the example, the current message window says both of these things:
+
+```text
+doorA is open
+doorA is closed
+```
+
+That is the inconsistency the example is meant to fix.
+
+---
+
+## Why ordinary merging is not enough
+
+If all messages are merged into one graph, the system sees both facts at once.
+
+For safety automation, that is not a useful final state. The system needs a current operational conclusion, such as:
+
+```text
+mark the fire compartment as sealed
+```
+
+or:
+
+```text
+send a technician to inspect and close the fire door
+```
+
+The example therefore separates two steps:
+
+1. detect the raw conflict,
+2. repair it before producing the final action.
+
+---
+
+## The message log
+
+The input file is a real RDF Message Log:
+
+```trig
+VERSION "1.2-messages"
+```
+
+Each `MESSAGE` delimiter separates one communication event from the next.
+
+Eyeling parses those delimiters before ordinary reasoning starts and exposes a replay model with `eymsg:` terms:
+
+- one stream,
+- one envelope per message,
+- ordered envelope links,
+- offsets,
+- and one payload graph per non-empty message.
+
+The rules reason over that replay model rather than pretending the stream was one big static graph.
+
+---
+
+## The five messages
+
+The log has five messages.
+
+Message 1 is policy and vocabulary:
+
+- the sliding ABox window has size 3,
+- the repair policy prefers higher-priority evidence,
+- `:open` and `:closed` map to operational action text.
+
+Messages 2 to 5 are door-state assertions.
+
+---
+
+## The sliding windows
+
+The previous window contains messages 2, 3, and 4.
+
+The current window contains messages 3, 4, and 5.
+
+So when the window advances:
+
+- message 2 expires,
+- messages 3 and 4 are retained,
+- message 5 enters.
+
+This is the small stream-reasoning shape the example demonstrates.
+
+---
+
+## The inconsistency
+
+In the current window:
+
+- message 3 says `doorA` is `:open`,
+- message 4 says `doorA` is `:closed`,
+- message 5 also says `doorA` is `:closed`.
+
+The raw materialized window therefore contains an open/closed contradiction.
+
+The example records this explicitly as:
+
+```n3
+:currentWindow :rawConflict :doorOpenAndClosed .
+```
+
+---
+
+## The repair policy
+
+The repair policy is deliberately simple:
+
+> If two current-window assertions conflict, keep the one with the higher priority.
+
+The camera and latch readings have priority 1.
+
+The safety-controller reading has priority 3.
+
+So the repaired state is:
+
+```text
+doorA is closed
+```
+
+The lower-priority conflicting open assertion is still visible as rejected evidence; it is not silently erased.
+
+---
+
+## The final materialization
+
+After repair, the rules derive the final action from the repaired state, not from the inconsistent raw window.
+
+For this data, the final action is:
+
+```text
+mark the fire compartment as sealed
+```
+
+That conclusion is only produced after the example has shown all of these things:
+
+- the RDF Message Log was replayed,
+- the sliding windows were constructed,
+- the raw open/closed conflict was detected,
+- the preferred repair selected the higher-priority assertion,
+- and the repaired state was materialized.
+
+---
+
+## What this example is useful for
+
+This is a compact pattern for stream-style reasoning with noisy inputs.
+
+It shows that RDF messages can be used as more than a transport format: their boundaries become part of the evidence.
+
+That makes it possible to explain conclusions in terms of:
+
+- which message arrived,
+- which window it belonged to,
+- whether it expired, was retained, or entered,
+- whether it conflicted with another message,
+- and why one assertion was preferred over another.

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

@@ -1,5 +1,7 @@
 # Mapping two data models (beginner-friendly)
 
+[Start with the source](../schema-foaf-mapping.n3) to see the vocabulary mapping rules; the [golden output](../output/schema-foaf-mapping.n3) shows the FOAF-shaped facts derived from the Schema.org-shaped input.
+
 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).**