eyeling 1.26.7 → 1.27.1

package/HANDBOOK.md

@@ -333,6 +333,36 @@ This is the important mental model for `-r` with RDF Messages: the parser preser
 
 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
 
 The parser supports:
@@ -2623,6 +2653,7 @@ Options:
   -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.
@@ -2663,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 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.
+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,16 @@ module.exports = {
 
 'use strict';
 
+const fs = require('node:fs');
+const os = require('node:os');
 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 +4670,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' });
 }
 
@@ -4674,6 +4677,10 @@ function __isNetworkOrFileIri(s) {
   return typeof s === 'string' && /^(https?:|file:\/\/)/i.test(s);
 }
 
+function __isHttpSource(s) {
+  return typeof s === 'string' && /^https?:/i.test(s);
+}
+
 function __sourceLabelToBaseIri(sourceLabel) {
   if (!sourceLabel || sourceLabel === '<stdin>') return '';
   if (__isNetworkOrFileIri(sourceLabel)) return deref.stripFragment(sourceLabel);
@@ -4689,10 +4696,492 @@ function __readInputSourceSync(sourceLabel) {
     return txt;
   }
 
-  const fs = require('node:fs');
   return fs.readFileSync(sourceLabel, { encoding: 'utf8' });
 }
 
+function __httpFetchScriptBody({ prefixOnly = false } = {}) {
+  return `
+    const fs = require('fs');
+    const http = require('http');
+    const https = require('https');
+    const zlib = require('zlib');
+    const { URL } = require('url');
+    const urlArg = process.argv[1];
+    const outFile = process.argv[2] || '';
+    const limit = Math.max(1, Number(process.argv[3] || 65536));
+    const prefixOnly = ${prefixOnly ? 'true' : 'false'};
+    const maxRedirects = 10;
+    function requestUrl(u, redirects) {
+      if (redirects > maxRedirects) { console.error('Too many redirects'); process.exit(3); }
+      const parsed = new URL(u);
+      const mod = parsed.protocol === 'https:' ? https : parsed.protocol === 'http:' ? http : null;
+      if (!mod) { console.error('Unsupported protocol ' + parsed.protocol); process.exit(2); }
+      const headers = {
+        accept: 'text/n3, text/turtle, application/trig, application/n-triples, application/n-quads, text/plain;q=0.8, */*;q=0.01',
+        'accept-encoding': 'identity',
+        'user-agent': 'eyeling-rdf-message-stream'
+      };
+      if (prefixOnly) headers.range = 'bytes=0-' + String(limit - 1);
+      const req = mod.request({
+        protocol: parsed.protocol,
+        hostname: parsed.hostname,
+        port: parsed.port || undefined,
+        path: parsed.pathname + parsed.search,
+        headers,
+      }, (res) => {
+        const sc = res.statusCode || 0;
+        if (sc >= 300 && sc < 400 && res.headers && res.headers.location) {
+          const next = new URL(res.headers.location, u).toString();
+          res.resume();
+          return requestUrl(next, redirects + 1);
+        }
+        if (sc < 200 || sc >= 300) {
+          res.resume();
+          console.error('HTTP status ' + sc);
+          process.exit(4);
+        }
+        const enc = String((res.headers && res.headers['content-encoding']) || '').toLowerCase();
+        let body = res;
+        if (enc.includes('gzip')) body = res.pipe(zlib.createGunzip());
+        else if (enc.includes('deflate')) body = res.pipe(zlib.createInflate());
+        else if (enc.includes('br')) body = res.pipe(zlib.createBrotliDecompress());
+        if (prefixOnly) {
+          const chunks = [];
+          let bytes = 0;
+          let finished = false;
+          function finish() {
+            if (finished) return;
+            finished = true;
+            const buf = Buffer.concat(chunks, bytes).subarray(0, limit);
+            process.stdout.write(buf.toString('utf8'));
+            process.exit(0);
+          }
+          body.on('data', (chunk) => {
+            if (finished) return;
+            chunks.push(chunk);
+            bytes += chunk.length;
+            if (bytes >= limit) finish();
+          });
+          body.on('end', finish);
+          body.on('error', (e) => { console.error(e && e.message ? e.message : String(e)); process.exit(5); });
+          return;
+        }
+        const out = fs.createWriteStream(outFile);
+        body.pipe(out);
+        body.on('error', (e) => { console.error(e && e.message ? e.message : String(e)); process.exit(5); });
+        out.on('error', (e) => { console.error(e && e.message ? e.message : String(e)); process.exit(6); });
+        out.on('finish', () => process.exit(0));
+      });
+      req.on('error', (e) => { console.error(e && e.message ? e.message : String(e)); process.exit(5); });
+      req.end();
+    }
+    requestUrl(urlArg, 0);
+  `;
+}
+
+function __readHttpPrefixSync(sourceLabel, byteLimit = 64 * 1024) {
+  const cp = require('node:child_process');
+  const r = cp.spawnSync(process.execPath, ['-e', __httpFetchScriptBody({ prefixOnly: true }), sourceLabel, '', String(byteLimit)], {
+    encoding: 'utf8',
+    maxBuffer: byteLimit + 16 * 1024,
+  });
+  if (r.status !== 0) throw new Error(`Failed to dereference ${sourceLabel}${r.stderr ? ': ' + String(r.stderr).trim() : ''}`);
+  return r.stdout;
+}
+
+function __downloadHttpSourceToTempFileSync(sourceLabel) {
+  const cp = require('node:child_process');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'eyeling-rdf-message-log-'));
+  const file = path.join(dir, 'source.txt');
+  const r = cp.spawnSync(process.execPath, ['-e', __httpFetchScriptBody({ prefixOnly: false }), sourceLabel, file], {
+    encoding: 'utf8',
+    maxBuffer: 1024 * 1024,
+    stdio: ['ignore', 'ignore', 'pipe'],
+  });
+  if (r.status !== 0) {
+    try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+    throw new Error(`Failed to dereference ${sourceLabel}${r.stderr ? ': ' + String(r.stderr).trim() : ''}`);
+  }
+  return { file, cleanup: () => { try { fs.rmSync(dir, { recursive: true, force: true }); } catch {} } };
+}
+
+
+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);
+    }
+  }
+  if (__isHttpSource(sourceLabel)) {
+    return RDF_MESSAGE_VERSION_RE.test(__readHttpPrefixSync(sourceLabel));
+  }
+  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;
+  }
+  if (__isHttpSource(sourceLabel)) {
+    const tmp = __downloadHttpSourceToTempFileSync(sourceLabel);
+    try {
+      forEachRdfMessageChunkInFileSync(tmp.file, onMessage);
+    } finally {
+      tmp.cleanup();
+    }
+    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 +5212,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 +5254,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 +5277,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 +5320,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.
 
 ---