eyeling 1.26.7 → 1.27.1

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

@@ -1,6 +1,6 @@
 # RDF Message window repair — fixing an open/closed door conflict
 
-This deck explains the example `rdf-message-window-repair.n3` and its input file `input/rdf-message-window-repair.trig`.
+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.
 

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).**