eyeling 1.26.6 → 1.27.0

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,94 @@ 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.
+
+
+#### Streaming large RDF Message Logs with `--stream-messages`
+
+The ordinary `-r` replay described above is intentionally a faithful whole-log replay: it materializes one stream resource, the complete ordered-envelope list, all envelope links, and all payload graphs before reasoning. That is useful for examples, audits, proofs, and rules that need to see the whole log at once, but it is not the right execution model for very large append-only logs.
+
+For large files where each RDF Message can be processed independently, use:
+
+```sh
+eyeling -r --stream-messages rules.n3 large-message-log.trig
+```
+
+`--stream-messages` keeps the rule files loaded once, then reads each RDF Message chunk from the log and runs the rules against a one-message replay view:
+
+```n3
+?stream a eymsg:RDFMessageStream;
+  eymsg:envelope ?envelope;
+  eymsg:firstEnvelope ?envelope;
+  eymsg:lastEnvelope ?envelope;
+  eymsg:orderedEnvelopes (?envelope).
+
+?envelope a eymsg:MessageEnvelope;
+  eymsg:offset ?n;
+  eymsg:payloadKind eymsg:nonEmpty;
+  eymsg:payloadGraph ?payload.
+```
+
+The payload is still scoped behind `?payload log:nameOf { ... }`, so rules use the same `log:nameOf`/`log:includes` pattern as in whole-log replay. The important difference is lifetime: after one message has been parsed, reasoned over, and printed, its facts are discarded before the next message is read. Local files are scanned incrementally instead of first being normalized into one giant N3 document.
+
+This mode is meant for production-style message feeds such as MARC-record streams, telemetry streams, or LDES member logs where a consumer checkpoint already tells the application which messages are new. It deliberately does not expose `eymsg:nextEnvelope` links or a complete `eymsg:messageCount`, because those require holding global stream state. Use ordinary `eyeling -r` when your rules need global ordering, sliding windows across several messages, or proof output for the entire replay.
 
 ### 4.2 Parsing triples, with Turtle-style convenience
 
@@ -2557,6 +2652,8 @@ 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.
+      --stream-messages        Process RDF Message Logs one message at a time under -r.
   -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 +2694,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. For large independent message logs, `--stream-messages` runs the same payload-inspection style one message at a time. 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/dist/browser/eyeling.browser.js

@@ -4622,12 +4622,15 @@ module.exports = {
 
 'use strict';
 
+const fs = require('node:fs');
 const path = require('node:path');
-const { pathToFileURL } = require('node:url');
+const { pathToFileURL, fileURLToPath } = require('node:url');
+const { TextDecoder } = require('node:util');
 
 const engine = require('./engine');
 const deref = require('./deref');
 const { PrefixEnv } = require('./prelude');
+const { normalizeRdfCompatibility } = require('./lexer');
 const { parseN3Text, mergeParsedDocuments } = require('./multisource');
 
 function offsetToLineCol(text, offset) {
@@ -4666,7 +4669,6 @@ function formatN3SyntaxError(err, text, path) {
 
 // CLI entry point (invoked when eyeling.js is run directly)
 function readTextFromStdinSync() {
-  const fs = require('node:fs');
   return fs.readFileSync(0, { encoding: 'utf8' });
 }
 
@@ -4689,10 +4691,374 @@ function __readInputSourceSync(sourceLabel) {
     return txt;
   }
 
-  const fs = require('node:fs');
   return fs.readFileSync(sourceLabel, { encoding: 'utf8' });
 }
 
+
+const RDF_MESSAGE_VERSION_RE = /^\s*(?:@version|VERSION)\s+(["'])(?:1\.1|1\.2|1\.2-basic)-messages\1\s*\.?\s*(?:#.*)?$/im;
+const RDF_MESSAGE_VERSION_LINE_RE = /^\s*(?:@version|VERSION)\s+(["'])(?:1\.1|1\.2|1\.2-basic)-messages\1\s*\.?\s*(?:#.*)?$/i;
+const RDF_DIRECTIVE_LINE_RE = /^\s*(?:@?(?:prefix|base)\b|PREFIX\b|BASE\b)/i;
+const RDF_MESSAGE_DELIMITER_LINE_RE = /^\s*(?:MESSAGE\b|@message\s*\.?)\s*(?:#.*)?$/i;
+const LOG_NAME_OF_IRI = '<http://www.w3.org/2000/10/swap/log#nameOf>';
+const RDF_TYPE_IRI = '<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>';
+const XSD_INTEGER_IRI = '<http://www.w3.org/2001/XMLSchema#integer>';
+const EYMSG_NS = 'https://eyereasoner.github.io/eyeling/vocab/message#';
+const EYMSG_IRIS = Object.freeze({
+  RDFMessageStream: `<${EYMSG_NS}RDFMessageStream>`,
+  MessageEnvelope: `<${EYMSG_NS}MessageEnvelope>`,
+  envelope: `<${EYMSG_NS}envelope>`,
+  firstEnvelope: `<${EYMSG_NS}firstEnvelope>`,
+  lastEnvelope: `<${EYMSG_NS}lastEnvelope>`,
+  orderedEnvelopes: `<${EYMSG_NS}orderedEnvelopes>`,
+  offset: `<${EYMSG_NS}offset>`,
+  payloadGraph: `<${EYMSG_NS}payloadGraph>`,
+  payloadKind: `<${EYMSG_NS}payloadKind>`,
+  empty: `<${EYMSG_NS}empty>`,
+  nonEmpty: `<${EYMSG_NS}nonEmpty>`,
+});
+
+function simpleHashText(s) {
+  let h = 0x811c9dc5;
+  const text = String(s || '');
+  for (let i = 0; i < text.length; i += 1) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+function __isLocalPathSource(sourceLabel) {
+  return typeof sourceLabel === 'string' && sourceLabel !== '<stdin>' && !/^(https?:|file:\/\/)/i.test(sourceLabel);
+}
+
+function __localPathForSource(sourceLabel) {
+  if (__isLocalPathSource(sourceLabel)) return sourceLabel;
+  if (typeof sourceLabel === 'string' && /^file:\/\//i.test(sourceLabel)) return fileURLToPath(sourceLabel);
+  return null;
+}
+
+function __sourceLooksLikeRdfMessageLogSync(sourceLabel) {
+  const filePath = __localPathForSource(sourceLabel);
+  if (filePath) {
+    const fd = fs.openSync(filePath, 'r');
+    try {
+      const buf = Buffer.allocUnsafe(64 * 1024);
+      const n = fs.readSync(fd, buf, 0, buf.length, 0);
+      return RDF_MESSAGE_VERSION_RE.test(buf.toString('utf8', 0, n));
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
+  return RDF_MESSAGE_VERSION_RE.test(__readInputSourceSync(sourceLabel));
+}
+
+function stripRdfDirectiveLines(text) {
+  return String(text || '')
+    .split(/(?<=\r\n|\n|\r)/)
+    .filter((line) => !RDF_DIRECTIVE_LINE_RE.test(line) && !RDF_MESSAGE_VERSION_LINE_RE.test(line))
+    .join('');
+}
+
+function hasRdfPayload(text) {
+  return String(text || '')
+    .split(/\r\n|\n|\r/)
+    .some((line) => {
+      const trimmed = line.replace(/#.*$/g, '').trim();
+      return trimmed && !RDF_DIRECTIVE_LINE_RE.test(trimmed) && !RDF_MESSAGE_VERSION_LINE_RE.test(trimmed);
+    });
+}
+
+function addRdfDirective(directives, seen, line) {
+  if (!RDF_DIRECTIVE_LINE_RE.test(line)) return;
+  const key = line.trim();
+  if (!key || seen.has(key)) return;
+  seen.add(key);
+  directives.push(line.endsWith('\n') || line.endsWith('\r') ? line : line + '\n');
+}
+
+function normalizeStreamingPayloadChunk(chunk, directives) {
+  const prelude = directives.join('');
+  const normalized = normalizeRdfCompatibility(prelude + String(chunk || ''));
+  return stripRdfDirectiveLines(normalized).trim();
+}
+
+function buildSingleMessageReplayDocument({ sourceLabel, messageIndex, chunk, directives }) {
+  const hash = simpleHashText(sourceLabel || '<stream>');
+  const base = `urn:eyeling:message-stream:${hash}`;
+  const padded = String(messageIndex).padStart(6, '0');
+  const stream = `<${base}#stream>`;
+  const envelope = `<${base}#m${padded}>`;
+  const payload = `<${base}#m${padded}/payload>`;
+  const body = normalizeStreamingPayloadChunk(chunk, directives);
+  const hasBody = hasRdfPayload(body);
+  const out = [];
+
+  out.push(...directives.map((line) => line.trim()).filter(Boolean));
+  out.push(`${stream} ${RDF_TYPE_IRI} ${EYMSG_IRIS.RDFMessageStream} .`);
+  out.push(`${stream} ${EYMSG_IRIS.envelope} ${envelope} .`);
+  out.push(`${stream} ${EYMSG_IRIS.orderedEnvelopes} (${envelope}) .`);
+  out.push(`${stream} ${EYMSG_IRIS.firstEnvelope} ${envelope} .`);
+  out.push(`${stream} ${EYMSG_IRIS.lastEnvelope} ${envelope} .`);
+  out.push(`${envelope} ${RDF_TYPE_IRI} ${EYMSG_IRIS.MessageEnvelope} .`);
+  out.push(`${envelope} ${EYMSG_IRIS.offset} "${messageIndex}"^^${XSD_INTEGER_IRI} .`);
+  out.push(`${envelope} ${EYMSG_IRIS.payloadKind} ${hasBody ? EYMSG_IRIS.nonEmpty : EYMSG_IRIS.empty} .`);
+  if (hasBody) {
+    out.push(`${envelope} ${EYMSG_IRIS.payloadGraph} ${payload} .`);
+    out.push(`${payload} ${LOG_NAME_OF_IRI} {`);
+    out.push(body);
+    out.push(`} .`);
+  }
+  return out.join('\n') + '\n';
+}
+
+function forEachRdfMessageChunkInText(text, onMessage) {
+  const directives = [];
+  const seenDirectives = new Set();
+  let chunk = '';
+  let messageIndex = 1;
+  let sawVersion = false;
+  let sawDelimiter = false;
+
+  function emit() {
+    onMessage({ messageIndex, chunk, directives: directives.slice() });
+    messageIndex += 1;
+    chunk = '';
+  }
+
+  const lines = String(text || '').match(/.*(?:\r\n|\n|\r)|.+$/g) || [];
+  for (const line of lines) {
+    if (RDF_MESSAGE_VERSION_LINE_RE.test(line)) {
+      sawVersion = true;
+      continue;
+    }
+    if (RDF_MESSAGE_DELIMITER_LINE_RE.test(line)) {
+      emit();
+      sawDelimiter = true;
+      continue;
+    }
+    addRdfDirective(directives, seenDirectives, line);
+    chunk += line;
+  }
+  if (!sawVersion) throw new Error('not an RDF Message Log: missing VERSION "*-messages" directive');
+  if (sawDelimiter || hasRdfPayload(chunk)) emit();
+}
+
+function forEachLineInFileSync(filePath, onLine) {
+  const fd = fs.openSync(filePath, 'r');
+  const decoder = new TextDecoder('utf8');
+  const buf = Buffer.allocUnsafe(64 * 1024);
+  let carry = '';
+  try {
+    for (;;) {
+      const n = fs.readSync(fd, buf, 0, buf.length, null);
+      if (n === 0) break;
+      carry += decoder.decode(buf.subarray(0, n), { stream: true });
+      for (;;) {
+        const m = /\r\n|\n|\r/.exec(carry);
+        if (!m) break;
+        const end = m.index + m[0].length;
+        onLine(carry.slice(0, end));
+        carry = carry.slice(end);
+      }
+    }
+    carry += decoder.decode();
+    if (carry) onLine(carry);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function forEachRdfMessageChunkInFileSync(filePath, onMessage) {
+  const directives = [];
+  const seenDirectives = new Set();
+  let chunk = '';
+  let messageIndex = 1;
+  let sawVersion = false;
+  let sawDelimiter = false;
+
+  function emit() {
+    onMessage({ messageIndex, chunk, directives: directives.slice() });
+    messageIndex += 1;
+    chunk = '';
+  }
+
+  forEachLineInFileSync(filePath, (line) => {
+    if (RDF_MESSAGE_VERSION_LINE_RE.test(line)) {
+      sawVersion = true;
+      return;
+    }
+    if (RDF_MESSAGE_DELIMITER_LINE_RE.test(line)) {
+      emit();
+      sawDelimiter = true;
+      return;
+    }
+    addRdfDirective(directives, seenDirectives, line);
+    chunk += line;
+  });
+
+  if (!sawVersion) throw new Error('not an RDF Message Log: missing VERSION "*-messages" directive');
+  if (sawDelimiter || hasRdfPayload(chunk)) emit();
+}
+
+
+function __forEachRdfMessageChunkSync(sourceLabel, onMessage) {
+  const filePath = __localPathForSource(sourceLabel);
+  if (filePath) {
+    forEachRdfMessageChunkInFileSync(filePath, onMessage);
+    return;
+  }
+  forEachRdfMessageChunkInText(__readInputSourceSync(sourceLabel), onMessage);
+}
+
+function factsContainOutputStrings(triplesForOutput) {
+  const LOG_OUTPUT_STRING = 'http://www.w3.org/2000/10/swap/log#outputString';
+  return (
+    Array.isArray(triplesForOutput) &&
+    triplesForOutput.some(
+      (tr) => tr && tr.p && tr.p.constructor && tr.p.constructor.name === 'Iri' && tr.p.value === LOG_OUTPUT_STRING,
+    )
+  );
+}
+
+function programMayProduceOutputStrings(topLevelTriples, forwardRules, logQueryRules) {
+  const hasOutputStringPredicate = (trs) => factsContainOutputStrings(trs);
+  if (hasOutputStringPredicate(topLevelTriples)) return true;
+  if (Array.isArray(forwardRules) && forwardRules.some((r) => hasOutputStringPredicate(r && r.conclusion))) return true;
+  if (Array.isArray(logQueryRules) && logQueryRules.some((r) => hasOutputStringPredicate(r && r.conclusion))) return true;
+  return false;
+}
+
+function runParsedDocumentOnce(mergedDocument, { rdfMode = false, outputPrefixes = null } = {}) {
+  const prefixes = mergedDocument.prefixes;
+  const triples = mergedDocument.triples;
+  const frules = mergedDocument.frules;
+  const brules = mergedDocument.brules;
+  const qrules = mergedDocument.logQueryRules;
+
+  engine.materializeRdfLists(triples, frules.concat(qrules || []), brules);
+  const facts = triples.slice();
+  const hasQueries = Array.isArray(qrules) && qrules.length;
+  const mayAutoRenderOutputStrings = programMayProduceOutputStrings(triples, frules, qrules);
+
+  let derived = [];
+  let outTriples = [];
+  if (hasQueries) {
+    const res = engine.forwardChainAndCollectLogQueryConclusions(facts, frules, brules, qrules, { prefixes });
+    derived = res.derived;
+    outTriples = res.queryTriples;
+  } else {
+    const skipDerivedCollection = mayAutoRenderOutputStrings;
+    derived = engine.forwardChain(facts, frules, brules, null, {
+      captureExplanations: false,
+      collectDerived: !skipDerivedCollection,
+      prefixes,
+    });
+    outTriples = skipDerivedCollection ? [] : derived.map((df) => df.fact);
+  }
+
+  const renderedOutputTriples = hasQueries ? outTriples : facts;
+  if (factsContainOutputStrings(renderedOutputTriples)) {
+    process.stdout.write(engine.collectOutputStringsFromFacts(renderedOutputTriples, prefixes));
+    return;
+  }
+
+  const outPrefixEnv = outputPrefixes || prefixes;
+  if (rdfMode) {
+    for (const tr of outTriples) console.log(engine.tripleToRdfCompatible(tr, outPrefixEnv));
+  } else if (hasQueries) {
+    const bodyText = engine.prettyPrintQueryTriples(outTriples, outPrefixEnv);
+    if (bodyText) process.stdout.write(String(bodyText).replace(/\s*$/g, '') + '\n');
+  } else {
+    for (const df of derived) console.log(engine.tripleToN3(df.fact, outPrefixEnv));
+  }
+}
+
+function runStreamMessagesMode(sourceLabels, { rdfMode }) {
+  const ordinarySourceLabels = [];
+  const messageSourceLabels = [];
+
+  for (const sourceLabel of sourceLabels) {
+    try {
+      if (__sourceLooksLikeRdfMessageLogSync(sourceLabel)) messageSourceLabels.push(sourceLabel);
+      else ordinarySourceLabels.push(sourceLabel);
+    } catch (e) {
+      console.error(`Error reading source ${JSON.stringify(sourceLabel)}: ${e && e.message ? e.message : String(e)}`);
+      process.exit(1);
+    }
+  }
+
+  if (!messageSourceLabels.length) {
+    console.error('Error: --stream-messages did not find any RDF Message Log input.');
+    process.exit(1);
+  }
+
+  const programSources = [];
+  for (const sourceLabel of ordinarySourceLabels) {
+    let text;
+    try {
+      text = __readInputSourceSync(sourceLabel);
+    } catch (e) {
+      if (sourceLabel === '<stdin>') console.error(`Error reading stdin: ${e.message}`);
+      else console.error(`Error reading source ${JSON.stringify(sourceLabel)}: ${e.message}`);
+      process.exit(1);
+    }
+
+    try {
+      programSources.push(
+        parseN3Text(text, {
+          baseIri: __sourceLabelToBaseIri(sourceLabel),
+          label: sourceLabel,
+          keepSourceArtifacts: false,
+          sourceLocations: false,
+          rdf: rdfMode,
+        }),
+      );
+    } catch (e) {
+      if (e && e.name === 'N3SyntaxError') {
+        console.error(formatN3SyntaxError(e, text, sourceLabel));
+        process.exit(1);
+      }
+      throw e;
+    }
+  }
+
+  const fullIriPrefixes = new PrefixEnv({});
+  for (const messageSourceLabel of messageSourceLabels) {
+    try {
+      __forEachRdfMessageChunkSync(messageSourceLabel, ({ messageIndex, chunk, directives }) => {
+        const messageText = buildSingleMessageReplayDocument({
+          sourceLabel: messageSourceLabel,
+          messageIndex,
+          chunk,
+          directives,
+        });
+        let messageDoc;
+        try {
+          messageDoc = parseN3Text(messageText, {
+            baseIri: `${__sourceLabelToBaseIri(messageSourceLabel)}#message-${messageIndex}`,
+            label: `${messageSourceLabel}#message-${messageIndex}`,
+            keepSourceArtifacts: false,
+            sourceLocations: false,
+            rdf: false,
+          });
+        } catch (e) {
+          if (e && e.name === 'N3SyntaxError') {
+            console.error(formatN3SyntaxError(e, messageText, `${messageSourceLabel}#message-${messageIndex}`));
+            process.exit(1);
+          }
+          throw e;
+        }
+
+        const merged = mergeParsedDocuments(programSources.concat([messageDoc]));
+        runParsedDocumentOnce(merged, { rdfMode, outputPrefixes: fullIriPrefixes });
+      });
+    } catch (e) {
+      console.error(`Error streaming RDF Message Log ${JSON.stringify(messageSourceLabel)}: ${e && e.message ? e.message : String(e)}`);
+      process.exit(1);
+    }
+  }
+}
+
 function main() {
   // Drop "node" and script name; keep only user-provided args
   // Expand combined short options: -pt == -p -t
@@ -4723,6 +5089,7 @@ function main() {
       `  -h, --help                   Show this help and exit.\n` +
       `  -p, --proof                  Enable proof explanations.\n` +
       `  -r, --rdf                    Enable RDF/TriG input/output compatibility.\n` +
+      `      --stream-messages        Process RDF Message Logs one message at a time under -r.\n` +
       `  -s, --super-restricted       Disable all builtins except => and <=.\n` +
       `  -t, --stream                 Stream derived triples as soon as they are derived.\n` +
       `  -v, --version                Print version and exit.\n`;
@@ -4764,6 +5131,7 @@ function main() {
 
   const showAst = argv.includes('--ast') || argv.includes('-a');
   const streamMode = argv.includes('--stream') || argv.includes('-t');
+  const streamMessagesMode = argv.includes('--stream-messages');
   const rdfMode = argv.includes('--rdf') || argv.includes('-r');
 
   // --enforce-https: rewrite http:// -> https:// for log dereferencing builtins
@@ -4786,6 +5154,26 @@ function main() {
     if (typeof engine.setSuperRestrictedMode === 'function') engine.setSuperRestrictedMode(true);
   }
 
+
+  if (streamMessagesMode) {
+    if (!rdfMode) {
+      console.error('Error: --stream-messages requires -r/--rdf.');
+      process.exit(1);
+    }
+    if (showAst) {
+      console.error('Error: --stream-messages cannot be combined with --ast.');
+      process.exit(1);
+    }
+    if (streamMode) {
+      console.error('Error: --stream-messages cannot be combined with --stream.');
+      process.exit(1);
+    }
+    if (engine.getProofCommentsEnabled()) {
+      console.error('Error: --stream-messages currently does not support proof output.');
+      process.exit(1);
+    }
+  }
+
   // Positional args (one or more N3 sources).
   const useImplicitStdin = positional.length === 0 && !process.stdin.isTTY;
   if (positional.length === 0 && !useImplicitStdin) {
@@ -4809,6 +5197,11 @@ function main() {
     process.exit(1);
   }
 
+  if (streamMessagesMode) {
+    runStreamMessagesMode(sourceLabels, { rdfMode });
+    return;
+  }
+
   const parsedSources = [];
   for (const sourceLabel of sourceLabels) {
     let text;

package/examples/deck/act-barley-seed-lineage.md

@@ -1,6 +1,6 @@
 # ACT barley seed lineage — can and can't
 
-This deck explains the example `act-barley-seed-lineage-can-and-cant.n3`.
+[Start with the source](../act-barley-seed-lineage.n3) to see the ACT model itself; the [golden output](../output/act-barley-seed-lineage.md) shows the lineage conclusions that Eyeling derives from it.
 
 The aim is to show how **Applied Constructor Theory** can describe a concrete biological case in Notation3 while doing both sides of Chiara Marletto’s formula:
 

package/examples/deck/faltings-genus2-finiteness.md

@@ -1,6 +1,6 @@
 # Faltings’ theorem (emulated) in Notation3: a genus‑2 curve over Q
 
-This deck explains the example `faltings-genus2-finiteness.n3` ([Playground][1]).
+[Start with the source](../faltings-genus2-finiteness.n3) for the emulated theorem statement and inference rules; the [golden output](../output/faltings-genus2-finiteness.n3) shows the finite-rational-points conclusion produced by the example.
 
 The goal is to show—at a friendly, “wide audience” level—how an N3 file can _model_ a famous mathematical implication:
 

package/examples/deck/high-trust-rdf-bloom-envelope.md

@@ -1,6 +1,6 @@
 # High-trust RDF graph lookup with a decimal certificate
 
-This deck explains the example `high-trust-rdf-bloom-envelope.n3` ([Playground][1]).
+[Start with the source](../high-trust-rdf-bloom-envelope.n3) for the Bloom-filter certificate and arithmetic checks; the [golden output](../output/high-trust-rdf-bloom-envelope.n3) shows the trust decision that Eyeling derives.
 
 The goal is to show that **advanced engineering claims can be expressed and checked in N3**, even when the claim involves a **transcendental quantity** such as `exp(-k*n/m)`.
 

package/examples/deck/odrl-dpv-risk-ranked.md

@@ -2,7 +2,7 @@
 
 ## Ranked, explainable output from machine-readable “Terms of Service”
 
-This deck explains how an agreement is modeled in **ODRL**, how risks are expressed in **DPV**, and how **N3 rules** connect the two into a ranked report. ([Playground][1])
+[Start with the source](../odrl-dpv-risk-ranked.n3) to inspect the machine-readable policy and risk rules; the [golden output](../output/odrl-dpv-risk-ranked.md) shows the ranked explanation produced from them.
 
 ---