eyeling 1.26.6 → 1.26.7

package/HANDBOOK.md

@@ -236,7 +236,15 @@ The lexer turns the input into tokens like:
 
 Parsing becomes dramatically simpler because tokenization already decided where strings end, where numbers are, and so on.
 
-By default, Eyeling parses ordinary N3. Selected RDF/TriG surface syntax is accepted only when RDF compatibility is explicitly enabled with `eyeling -r file.trig`, `eyeling --rdf file.trig`, or API option `{ rdf: true }`. In that mode, the lexer normalizes RDF/TriG input syntax to ordinary N3 graph terms before normal parsing, and the printer emits RDF/TriG-compatible output where feasible. Eyeling remains an N3 reasoner; this is syntax compatibility, not a separate RDF dataset reasoning model.
+By default, Eyeling parses ordinary N3. Selected RDF/TriG surface syntax is accepted only when RDF compatibility is explicitly enabled with `eyeling -r file.trig`, `eyeling --rdf file.trig`, or API option `{ rdf: true }`.
+
+The `-r` flag does **not** switch Eyeling to a different RDF dataset reasoner. It adds a parser/printer compatibility layer around the same N3 engine:
+
+1. before normal parsing, RDF/TriG surface syntax is normalized into ordinary Eyeling N3 terms;
+2. the usual N3 parser, rule compiler, forward chainer, backward prover, builtins, and output rendering then run on that normalized program;
+3. when possible, final output is printed back in RDF/TriG-compatible syntax.
+
+This matters because rules still reason over Eyeling's N3 term model. Named graphs become quoted formulas, RDF 1.2 triple terms become singleton quoted formulas, and RDF Message Logs become an explicit replay graph that ordinary N3 rules can consume.
 
 In RDF compatibility mode, RDF 1.2 triple terms written as `<<( s p o )>>`, plus the reified triple form `<<s p o ~ r>>`, are normalized to Eyeling's existing singleton quoted-formula term `{ s p o }`. A reifier `r` is preserved as `r rdf:reifies { s p o }`. A leading `VERSION "1.2"` or `@version "1.2"` directive is ignored for the same reason. On output, `--rdf` converts a singleton graph term back to `<<( ... )>>` only when its inner triple is valid as an RDF triple term; otherwise it stays in N3 graph-term form. It also prints `log:nameOf` graph-term triples back as TriG named graph blocks. For example:
 
@@ -266,7 +274,64 @@ is treated internally like:
 } .
 ```
 
-This keeps Eyeling's N3 model stable while allowing small RDF 1.1/RDF 1.2 dataset-shaped inputs to run through the existing `GraphTerm` machinery when the caller opts in. More exotic future RDF forms should be added only if they can be mapped cleanly onto Eyeling's quoted-formula term model.
+A top-level default graph block is unwrapped into ordinary top-level triples. A named graph block is not merged into the default graph; it remains a quoted formula reachable through `log:nameOf`.
+
+#### RDF Message Log replay under `-r`
+
+If RDF compatibility mode sees a top-level message version directive such as:
+
+```trig
+VERSION "1.2-messages"
+```
+
+or the corresponding `@version` spelling, Eyeling treats the input as an RDF Message Log before ordinary N3 parsing starts. The accepted message-version strings are `"1.1-messages"`, `"1.2-messages"`, and `"1.2-basic-messages"`.
+
+At top-level statement boundaries, `MESSAGE` and `@message` delimiters split the document into message chunks. The text before the first delimiter is the first message. An empty chunk is still a message: it is replayed as an empty heartbeat rather than being dropped. Directives and comments alone do not make a message non-empty.
+
+Each chunk is then normalized separately using the same RDF/TriG compatibility rules. Eyeling also scopes blank-node labels per message, so reusing `_:x` in two different messages does not accidentally identify the same blank node across message boundaries.
+
+The result of replay is not a hidden side channel. Eyeling materializes ordinary facts using the `eymsg:` vocabulary:
+
+```n3
+@prefix eymsg: <https://eyereasoner.github.io/eyeling/vocab/message#>.
+
+?stream a eymsg:RDFMessageStream;
+  eymsg:messageCount ?count;
+  eymsg:orderedEnvelopes ?envelopes;
+  eymsg:firstEnvelope ?first;
+  eymsg:lastEnvelope ?last;
+  eymsg:envelope ?envelope.
+
+?envelope a eymsg:MessageEnvelope;
+  eymsg:offset ?n;
+  eymsg:payloadKind eymsg:nonEmpty;
+  eymsg:payloadGraph ?payload;
+  eymsg:nextEnvelope ?next.
+```
+
+For an empty message, the envelope has `eymsg:payloadKind eymsg:empty` and no `eymsg:payloadGraph`. For a non-empty message, the payload is exposed as a named graph:
+
+```n3
+?payload log:nameOf {
+  ...the normalized message body...
+} .
+```
+
+That design is deliberate: message payload triples are **not silently merged** into the global fact store. Rules inspect a payload explicitly, usually with `log:nameOf` plus `log:includes`:
+
+```n3
+{
+  ?envelope eymsg:payloadGraph ?payload.
+  ?payload log:nameOf ?payloadGraph.
+  ?payloadGraph log:includes { :doorA :state :closed }.
+} => {
+  ?envelope :reportsClosed :doorA.
+}.
+```
+
+This is the important mental model for `-r` with RDF Messages: the parser preserves message order and message boundaries as data. Reasoning can then implement stream-like behavior—flow stages, sliding windows, heartbeats, conflict repair, replay audits—without the TriG sidecar having to invent envelope facts by hand.
+
+This keeps Eyeling's N3 model stable while allowing small RDF 1.1/RDF 1.2 dataset-shaped and message-log-shaped inputs to run through the existing `GraphTerm` machinery when the caller opts in. More exotic future RDF forms should be added only if they can be mapped cleanly onto Eyeling's quoted-formula term model.
 
 ### 4.2 Parsing triples, with Turtle-style convenience
 
@@ -2557,6 +2622,7 @@ Options:
   -e, --enforce-https          Rewrite http:// IRIs to https:// for log dereferencing builtins.
   -h, --help                   Show this help and exit.
   -p, --proof                  Enable proof explanations.
+  -r, --rdf                    Enable RDF/TriG input/output compatibility.
   -s, --super-restricted       Disable all builtins except => and <=.
   -t, --stream                 Stream derived triples as soon as they are derived.
   -v, --version                Print version and exit.
@@ -2597,7 +2663,7 @@ Quoted graphs/formulas use `{ ... }`. Inside a quoted formula, directive scope m
 
 - `@prefix/@base` and `PREFIX/BASE` directives may appear at top level **or inside `{ ... }`**, and apply to the formula they occur in (formula-local scoping).
 
-With `-r, --rdf` / `{ rdf: true }`, Eyeling also accepts RDF 1.2 triple-term surface forms such as `<<( s p o )>>` and `<<s p o ~ r>>` as compatibility spellings for a singleton quoted formula `{ s p o }`. In the same mode, feasible singleton graph terms are printed back as RDF 1.2 triple terms, while invalid cases such as a literal subject remain ordinary N3 graph terms. This is useful for inputs that use `rdf:reifies` or other predicates whose objects are RDF 1.2 triple terms, while keeping the default language and the rest of Eyeling on its N3 formula-term model.
+With `-r, --rdf` / `{ rdf: true }`, Eyeling accepts selected RDF/TriG surface syntax before normal N3 parsing. RDF 1.2 triple-term forms such as `<<( s p o )>>` and `<<s p o ~ r>>` are compatibility spellings for singleton quoted formulas such as `{ s p o }`; feasible singleton graph terms are printed back as RDF 1.2 triple terms. TriG named graph blocks become `log:nameOf` quoted formulas. If a `VERSION "1.2-messages"`-style directive is present, top-level `MESSAGE` delimiters are replayed as `eymsg:` stream/envelope facts and per-message payload graphs. See [Chapter 4.1](#41-lexing-tokens-not-magic) for the full `-r` model and RDF Message handling.
 
 For the formal grammar, see the N3 spec grammar:
 

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

@@ -0,0 +1,175 @@
+# 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`.
+
+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/input/rdf-message-window-repair.trig

@@ -0,0 +1,79 @@
+# =====================================
+# RDF Message Window Repair message log
+# =====================================
+#
+# This file is the data half of the runnable example:
+#
+#   eyeling -r examples/rdf-message-window-repair.n3 examples/input/rdf-message-window-repair.trig
+#
+# The log models a fire-door monitoring ABox stream. Message 1 is stable
+# configuration/TBox-like policy. Messages 2-5 are ordered ABox assertions. The
+# rules use a sliding window over the last three ABox messages and repair a noisy
+# contradiction by preferring the highest-priority assertion.
+
+VERSION "1.2-messages"
+PREFIX : <https://eyereasoner.github.io/eyeling/examples/rdf-message-window-repair#>
+PREFIX see: <https://example.org/see#>
+PREFIX in: <https://example.org/see/input#>
+PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+
+# Message 1: fixed stream policy and action vocabulary.
+:doorA a :FireDoor ;
+  :windowSize 3 ;
+  :repairPolicy :preferHigherPriority .
+
+:open :actionText "send a technician to inspect and close the fire door";
+  :stateText "open" .
+:closed :actionText "mark the fire compartment as sealed";
+  :stateText "closed" .
+
+in:run a see:InputDataset ;
+  see:name "rdf_message_window_repair" ;
+  see:title "RDF Message Window Repair" ;
+  see:sourceFile "examples/rdf-message-window-repair.n3" ;
+  see:description "A true RDF 1.2 Message Log for sliding-window repair of an open/closed fire-door inconsistency." ;
+  see:compiler "Eyeling RDF Message Log input" .
+
+MESSAGE
+
+# Message 2: the previous window starts with a normal closed reading. It expires
+# when the current window slides forward.
+:reading-001 a :DoorAssertion ;
+  :about :doorA ;
+  :doorState :closed ;
+  :priority 1 ;
+  :source "hallway-latch" ;
+  :observedAt "2026-05-12T18:20:00Z"^^xsd:dateTime .
+
+MESSAGE
+
+# Message 3: overlapping evidence retained in the next window. The camera says
+# the door is open.
+:reading-002 a :DoorAssertion ;
+  :about :doorA ;
+  :doorState :open ;
+  :priority 1 ;
+  :source "corridor-camera" ;
+  :observedAt "2026-05-12T18:20:30Z"^^xsd:dateTime .
+
+MESSAGE
+
+# Message 4: another overlapping reading conflicts with message 3: the latch
+# says the same door is closed.
+:reading-003 a :DoorAssertion ;
+  :about :doorA ;
+  :doorState :closed ;
+  :priority 1 ;
+  :source "hallway-latch" ;
+  :observedAt "2026-05-12T18:21:00Z"^^xsd:dateTime .
+
+MESSAGE
+
+# Message 5: entering high-priority safety-controller assertion. The preferred
+# repair keeps this assertion rather than the lower-priority conflicting fact.
+:reading-004 a :DoorAssertion ;
+  :about :doorA ;
+  :doorState :closed ;
+  :priority 3 ;
+  :source "safety-controller" ;
+  :observedAt "2026-05-12T18:21:30Z"^^xsd:dateTime .

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

@@ -0,0 +1,13 @@
+# rdf-message-window-repair  
+
+## Source files  
+
+- [N3 rules](../rdf-message-window-repair.n3)  
+- [Input RDF Message Log](../input/rdf-message-window-repair.trig)  
+- [Story deck](../deck/rdf-message-window-repair.md)  
+
+## Answer  
+Sliding-window RDF Message repair accepted: 5 parser-replayed messages produced two overlapping 3-message ABox windows. The current window retained two envelopes from the previous window, expired one old door reading, and added one new safety-controller reading. Its raw graph-level materialization was inconsistent because doorA was both open and closed. The preferred repair kept the priority-3 assertion from safety-controller, resolved the door state to closed, and materialized the action: mark the fire compartment as sealed.  
+
+## Explanation  
+The RDF Message Log uses VERSION \"1.2-messages\" and MESSAGE delimiters. Eyeling parses those boundaries into eymsg: envelopes and payload graphs; the rules inspect each payload with log:includes rather than merging message bodies by hand. The example mirrors a sliding-window stream-reasoning pattern: when the window advances, overlapping message evidence is retained, an expired assertion leaves the window, an entering assertion can change the materialization, and a preferred repair fixes a noisy open/closed contradiction before the final action is produced.  

package/examples/rdf-message-window-repair.n3

@@ -0,0 +1,163 @@
+# =========================
+# RDF Message Window Repair
+# =========================
+#
+# Run as:
+#
+#   eyeling -r examples/rdf-message-window-repair.n3 examples/input/rdf-message-window-repair.trig
+#
+# This example is inspired by incremental, inconsistency-resilient reasoning over
+# sliding ABox streams.  The input is a true RDF Message Log: each MESSAGE
+# boundary is parsed by Eyeling into an eymsg: envelope with one payload graph per
+# non-empty message.
+#
+# The rules below keep the message boundaries visible, select two overlapping
+# three-message windows, detect that the current window says the same fire door
+# is both open and closed, and repair the inconsistency by keeping the
+# higher-priority safety-controller assertion for the final materialization.
+
+@prefix : <https://eyereasoner.github.io/eyeling/examples/rdf-message-window-repair#>.
+@prefix eymsg: <https://eyereasoner.github.io/eyeling/vocab/message#>.
+@prefix math: <http://www.w3.org/2000/10/swap/math#>.
+@prefix list: <http://www.w3.org/2000/10/swap/list#>.
+@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 gives a static view of the message log: an
+# ordered list, explicit offsets, and next-envelope links.
+{
+  ?Stream a eymsg:RDFMessageStream;
+    eymsg:envelope ?Message.
+  ?Message a eymsg:MessageEnvelope;
+    eymsg:offset ?Offset.
+} => {
+  ?Message :boundaryExplicit true.
+  ?Message :offset ?Offset.
+}.
+
+# The first payload carries stream policy, like a fixed TBox/configuration that
+# is not itself part of the changing ABox window.
+{
+  ?Message eymsg:payloadGraph ?Payload.
+  ?Payload log:nameOf ?PayloadContext.
+  ?PayloadContext log:includes {
+    :doorA :windowSize ?WindowSize;
+      :repairPolicy :preferHigherPriority.
+    :open :actionText ?OpenAction;
+      :stateText ?OpenStateText.
+    :closed :actionText ?ClosedAction;
+      :stateText ?ClosedStateText.
+  }.
+} => {
+  :doorA :windowSize ?WindowSize;
+    :repairPolicy :preferHigherPriority.
+  :open :actionText ?OpenAction;
+    :stateText ?OpenStateText.
+  :closed :actionText ?ClosedAction;
+    :stateText ?ClosedStateText.
+}.
+
+# With five messages, message 1 is configuration and messages 2-5 are ABox
+# assertions.  The previous and current sliding windows overlap on messages 3
+# and 4; message 2 expires and message 5 enters.
+{
+  ?Stream a eymsg:RDFMessageStream;
+    eymsg:firstEnvelope ?M1.
+  ?M1 eymsg:nextEnvelope ?M2.
+  ?M2 eymsg:nextEnvelope ?M3.
+  ?M3 eymsg:nextEnvelope ?M4.
+  ?M4 eymsg:nextEnvelope ?M5.
+} => {
+  :previousWindow :contains ?M2, ?M3, ?M4.
+  :currentWindow :contains ?M3, ?M4, ?M5.
+  :windowSlide :expired ?M2;
+    :retained ?M3, ?M4;
+    :entered ?M5.
+}.
+
+# Inspect each message payload inside its own replayed RDF Message graph, then
+# lift only the ABox assertion metadata needed for window reasoning.
+{
+  ?Window :contains ?Message.
+  ?Message eymsg:payloadGraph ?Payload.
+  ?Payload log:nameOf ?PayloadContext.
+  ?PayloadContext log:includes {
+    ?Reading :about :doorA;
+      :doorState ?State;
+      :priority ?Priority;
+      :source ?Source.
+  }.
+} => {
+  ?Message :windowAssertion ?Reading;
+    :doorState ?State;
+    :priority ?Priority;
+    :source ?Source.
+  ?Window :hasDoorState ?State.
+}.
+
+# The current graph-level window is inconsistent: after raw materialization it
+# says the same door is both open and closed.
+{
+  :currentWindow :contains ?OpenMessage, ?ClosedMessage.
+  ?OpenMessage :doorState :open.
+  ?ClosedMessage :doorState :closed.
+} => {
+  :currentWindow :rawConflict :doorOpenAndClosed;
+    :inconsistentDoor :doorA.
+}.
+
+# Preferred repair: if a current-window assertion has higher priority than a
+# conflicting current-window assertion, keep the higher-priority assertion as the
+# one used by materialization.
+{
+  :currentWindow :contains ?PreferredMessage, ?RejectedMessage;
+    :rawConflict :doorOpenAndClosed.
+  ?PreferredMessage :doorState ?PreferredState;
+    :priority ?PreferredPriority;
+    :source ?PreferredSource.
+  ?RejectedMessage :doorState ?RejectedState;
+    :priority ?RejectedPriority.
+  ?PreferredState log:notEqualTo ?RejectedState.
+  ?PreferredPriority math:greaterThan ?RejectedPriority.
+} => {
+  :currentWindow :preferredRepairState ?PreferredState;
+    :preferredEvidence ?PreferredMessage;
+    :preferredSource ?PreferredSource;
+    :rejectsLowerPriority ?RejectedMessage;
+    :repairsInconsistency :doorOpenAndClosed;
+    :resolvedDoorState ?PreferredState.
+}.
+
+# Materialize the final operational conclusion from the repaired state rather
+# than from the inconsistent raw window.
+{
+  :currentWindow :preferredRepairState ?State.
+  ?State :actionText ?ActionText.
+} => {
+  :currentWindow :materializedActionText ?ActionText.
+}.
+
+# Emit a report only when the parser replay, sliding-window bookkeeping, raw
+# conflict, preferred repair, and final materialization were all derived.
+{
+  ?Stream a eymsg:RDFMessageStream;
+    eymsg:orderedEnvelopes ?Messages.
+  ?Messages list:length ?Count.
+  :doorA :windowSize ?WindowSize.
+  :previousWindow :contains ?PreviousOnly.
+  :windowSlide :expired ?PreviousOnly;
+    :retained ?Overlap1, ?Overlap2;
+    :entered ?Entered.
+  :currentWindow :rawConflict :doorOpenAndClosed;
+    :inconsistentDoor :doorA;
+    :preferredEvidence ?PreferredMessage;
+    :preferredSource ?PreferredSource;
+    :resolvedDoorState ?State;
+    :materializedActionText ?ActionText.
+  ?State :stateText ?StateText.
+  ?PreferredMessage :priority ?PreferredPriority.
+  ("# rdf-message-window-repair\n\n## Source files\n\n- [N3 rules](../rdf-message-window-repair.n3)\n- [Input RDF Message Log](../input/rdf-message-window-repair.trig)\n- [Story deck](../deck/rdf-message-window-repair.md)\n\n## Answer\nSliding-window RDF Message repair accepted: %d parser-replayed messages produced two overlapping %d-message ABox windows. The current window retained two envelopes from the previous window, expired one old door reading, and added one new safety-controller reading. Its raw graph-level materialization was inconsistent because doorA was both open and closed. The preferred repair kept the priority-%d assertion from %s, resolved the door state to %s, and materialized the action: %s.\n\n## Explanation\nThe RDF Message Log uses VERSION \\\"1.2-messages\\\" and MESSAGE delimiters. Eyeling parses those boundaries into eymsg: envelopes and payload graphs; the rules inspect each payload with log:includes rather than merging message bodies by hand. The example mirrors a sliding-window stream-reasoning pattern: when the window advances, overlapping message evidence is retained, an expired assertion leaves the window, an entering assertion can change the materialization, and a preferred repair fixes a noisy open/closed contradiction before the final action is produced." ?Count ?WindowSize ?PreferredPriority ?PreferredSource ?StateText ?ActionText) string:format ?Block.
+} => {
+  :rdfMessageWindowRepairExample log:outputString ?Block.
+  :rdfMessageWindowRepairExample :demonstrates :RDFMessageLogReplay, :SlidingWindow, :OverlappingWindows, :ABoxStream, :RawDoorInconsistency, :PreferredRepair, :IncrementalMaterialization.
+}.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.26.6",
+  "version": "1.26.7",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [