eyeling 1.26.7 → 1.27.0

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,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.
 
 ---
 

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.