eyeling 1.24.30 → 1.24.33

package/dist/browser/eyeling.browser.js

@@ -1207,25 +1207,36 @@ function parseXsdDateTerm(t) {
   return d;
 }
 
+function isXsdDateTimeDatatype(dt) {
+  return dt === XSD_NS + 'dateTime' || dt === XSD_NS + 'dateTimeStamp';
+}
+
 function parseXsdDatetimeTerm(t) {
   if (!(t instanceof Literal)) return null;
   const [lex, dt] = literalParts(t.value);
-  if (dt !== XSD_NS + 'dateTime') return null;
+  if (!isXsdDateTimeDatatype(dt)) return null;
   const val = stripQuotes(lex);
+
+  // xsd:dateTimeStamp is a subtype of xsd:dateTime with a required timezone.
+  // Keep xsd:dateTime's existing permissive behaviour, but reject stamp
+  // lexicals that do not actually carry the required timezone.
+  if (dt === XSD_NS + 'dateTimeStamp' && !/(Z|[+-]\d{2}:\d{2})$/.test(val)) return null;
+
   const d = new Date(val);
   if (Number.isNaN(d.getTime())) return null;
   return d; // Date in local/UTC, we only use timestamp
 }
 
 function parseXsdDateTimeLexParts(t) {
-  // Parse *lexical* components of an xsd:dateTime literal without timezone normalization.
+  // Parse *lexical* components of an xsd:dateTime/dateTimeStamp literal without timezone normalization.
   // Returns { yearStr, month, day, hour, minute, second, tz } or null.
   if (!(t instanceof Literal)) return null;
   const [lex, dt] = literalParts(t.value);
-  if (dt !== XSD_NS + 'dateTime') return null;
+  if (!isXsdDateTimeDatatype(dt)) return null;
   const val = stripQuotes(lex);
 
   // xsd:dateTime lexical: YYYY-MM-DDThh:mm:ss(.s+)?(Z|(+|-)hh:mm)?
+  // xsd:dateTimeStamp has the same lexical form, but with the timezone required.
   const m = /^(-?\d{4,})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(Z|[+-]\d{2}:\d{2})?$/.exec(val);
   if (!m) return null;
 
@@ -1236,6 +1247,7 @@ function parseXsdDateTimeLexParts(t) {
   const minute = parseInt(m[5], 10);
   const second = parseInt(m[6], 10);
   const tz = m[7] || null;
+  if (dt === XSD_NS + 'dateTimeStamp' && !tz) return null;
 
   if (!(month >= 1 && month <= 12)) return null;
   if (!(day >= 1 && day <= 31)) return null;
@@ -1302,7 +1314,8 @@ function parseIso8601DurationToSeconds(s) {
 }
 
 function parseNumericForCompareTerm(t) {
-  // Strict: only accept xsd numeric literals, xsd:duration, xsd:date, xsd:dateTime
+  // Strict: only accept xsd numeric literals, xsd:duration, xsd:date,
+  // xsd:dateTime, and xsd:dateTimeStamp.
   // (or untyped numeric tokens).
   const bi = parseIntLiteral(t);
   if (bi !== null) return { kind: 'bigint', value: bi };
@@ -1369,7 +1382,7 @@ function parseNumOrDuration(t) {
     }
   }
 
-  // xsd:date / xsd:dateTime
+  // xsd:date / xsd:dateTime / xsd:dateTimeStamp
   const dtval = parseDatetimeLike(t);
   if (dtval !== null) {
     return dtval.getTime() / 1000.0;
@@ -9769,6 +9782,24 @@ function stripQuotes(lex) {
 // This keeps all downstream parsing/reasoning N3-only.
 const LOG_NAME_OF_IRI = '<http://www.w3.org/2000/10/swap/log#nameOf>';
 const RDF_REIFIES_IRI = '<http://www.w3.org/1999/02/22-rdf-syntax-ns#reifies>';
+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 = 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>`,
+  messageCount: `<${EYMSG_NS}messageCount>`,
+  offset: `<${EYMSG_NS}offset>`,
+  nextEnvelope: `<${EYMSG_NS}nextEnvelope>`,
+  payloadGraph: `<${EYMSG_NS}payloadGraph>`,
+  payloadKind: `<${EYMSG_NS}payloadKind>`,
+  empty: `<${EYMSG_NS}empty>`,
+  nonEmpty: `<${EYMSG_NS}nonEmpty>`,
+});
 
 function normalizeRdfCompatibility(inputText) {
   let text = String(inputText ?? '');
@@ -9779,10 +9810,11 @@ function normalizeRdfCompatibility(inputText) {
   // plausible top-level TriG named graph block.
   const hasTripleTerms = text.includes('<<');
   const hasVersionDirective = /^\s*(?:@version|VERSION)\s+(["'])1\.2\1\s*\.?\s*(?:#.*)?$/im.test(text);
+  const hasMessageVersionDirective = /^\s*(?:@version|VERSION)\s+(["'])(?:1\.1|1\.2|1\.2-basic)-messages\1\s*\.?\s*(?:#.*)?$/im.test(text);
   const hasNamedGraphCandidate = /(?:^|[.\r\n])\s*(?:GRAPH\s+)?(?:<[^>\r\n]*>|_:[A-Za-z][A-Za-z0-9_-]*|[A-Za-z][A-Za-z0-9_-]*:[^\s{};,.()[\]]*)\s*\{/m.test(text);
   const hasAnnotationSyntax = /(?:^|\s)~\s*(?:<|_:[A-Za-z]|[A-Za-z][A-Za-z0-9_-]*:|\{\|)|\{\|/.test(text);
 
-  if (!hasTripleTerms && !hasVersionDirective && !hasNamedGraphCandidate && !hasAnnotationSyntax) return text;
+  if (!hasTripleTerms && !hasVersionDirective && !hasMessageVersionDirective && !hasNamedGraphCandidate && !hasAnnotationSyntax) return text;
 
   function isWordChar(ch) {
     return ch != null && /[A-Za-z0-9_:-]/.test(ch);
@@ -10136,7 +10168,7 @@ function normalizeRdfCompatibility(inputText) {
   }
 
   function stripVersionDirectives(s) {
-    return s.replace(/^\s*(?:@version|VERSION)\s+(["'])1\.2\1\s*\.?\s*(?:#.*)?$/gim, '');
+    return s.replace(/^\s*(?:@version|VERSION)\s+(["'])(?:1\.1|1\.2|1\.2-basic)(?:-messages)?\1\s*\.?\s*(?:#.*)?$/gim, '');
   }
 
   function skipWsAndComments(s, at) {
@@ -10290,10 +10322,270 @@ function normalizeRdfCompatibility(inputText) {
     return out;
   }
 
+
+  function isOnlyWhitespaceAndComments(s) {
+    return skipWsAndComments(s, 0) >= s.length;
+  }
+
+
+  function skipOldStyleDirective(s, at) {
+    let i = at;
+    while (i < s.length) {
+      const ch = s[i];
+      if (ch === '"' || ch === "'") {
+        i = readStringAt(s, i).end;
+        continue;
+      }
+      if (ch === '<') {
+        i = readIriAt(s, i).end;
+        continue;
+      }
+      if (ch === '#') {
+        while (i < s.length && s[i] !== '\n' && s[i] !== '\r') i += 1;
+        continue;
+      }
+      i += 1;
+      if (ch === '.') return i;
+    }
+    return i;
+  }
+
+  function stripDirectivesAndCommentsForEmptiness(s) {
+    let out = '';
+    let i = 0;
+    let statementStart = true;
+    while (i < s.length) {
+      const ch = s[i];
+      if (ch === '"' || ch === "'") {
+        const str = readStringAt(s, i);
+        out += str.text;
+        i = str.end;
+        statementStart = false;
+        continue;
+      }
+      if (ch === '<') {
+        const iri = readIriAt(s, i);
+        out += iri.text;
+        i = iri.end;
+        statementStart = false;
+        continue;
+      }
+      if (ch === '#') {
+        while (i < s.length && s[i] !== '\n' && s[i] !== '\r') i += 1;
+        statementStart = true;
+        continue;
+      }
+      if (statementStart) {
+        const start = skipWsAndComments(s, i);
+        out += s.slice(i, start);
+        i = start;
+        if (startsWordAt(s, 'PREFIX', i) || startsWordAt(s, 'BASE', i) || startsWordAt(s, 'VERSION', i)) {
+          while (i < s.length && s[i] !== '\n' && s[i] !== '\r') i += 1;
+          statementStart = true;
+          continue;
+        }
+        if (s[i] === '@') {
+          const lower = s.slice(i, i + 9).toLowerCase();
+          if (lower.startsWith('@prefix') || lower.startsWith('@base') || lower.startsWith('@version')) {
+            i = skipOldStyleDirective(s, i);
+            statementStart = true;
+            continue;
+          }
+        }
+      }
+      out += ch;
+      if (ch === '.' || ch === '}' || ch === '\n' || ch === '\r') statementStart = true;
+      else if (!/\s/.test(ch)) statementStart = false;
+      i += 1;
+    }
+    return out;
+  }
+
+  function simpleHashText(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i += 1) {
+      h ^= s.charCodeAt(i);
+      h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h.toString(16).padStart(8, '0');
+  }
+
+  function rewriteMessageBlankLabels(s, messageIndex) {
+    let out = '';
+    let i = 0;
+    const prefix = `_:eyeling_m${String(messageIndex).padStart(3, '0')}_`;
+    while (i < s.length) {
+      const ch = s[i];
+      if (ch === '"' || ch === "'") {
+        const str = readStringAt(s, i);
+        out += str.text;
+        i = str.end;
+        continue;
+      }
+      if (ch === '<' && !s.startsWith('<<', i)) {
+        const iri = readIriAt(s, i);
+        out += iri.text;
+        i = iri.end;
+        continue;
+      }
+      if (ch === '#') {
+        while (i < s.length) {
+          const c = s[i++];
+          out += c;
+          if (c === '\n' || c === '\r') break;
+        }
+        continue;
+      }
+      if (s.startsWith('_:', i)) {
+        let j = i + 2;
+        while (j < s.length && !/\s/.test(s[j]) && !'{}[](),;.'.includes(s[j])) j += 1;
+        const label = s.slice(i + 2, j);
+        if (label) {
+          out += prefix + label.replace(/[^A-Za-z0-9_]/g, '_');
+          i = j;
+          continue;
+        }
+      }
+      out += ch;
+      i += 1;
+    }
+    return out;
+  }
+
+  function findMessageDirectiveAt(s, at) {
+    if (startsWordAt(s, 'MESSAGE', at)) return { start: at, end: at + 'MESSAGE'.length };
+    if (s.slice(at, at + 8).toLowerCase() === '@message' && !isWordChar(s[at + 8])) {
+      let end = at + 8;
+      end = skipWsAndComments(s, end);
+      if (s[end] === '.') end += 1;
+      return { start: at, end };
+    }
+    return null;
+  }
+
+  function splitRdfMessageLog(s) {
+    const chunks = [];
+    let i = 0;
+    let start = 0;
+    let braceDepth = 0;
+    let bracketDepth = 0;
+    let parenDepth = 0;
+    let statementStart = true;
+    let sawDelimiter = false;
+
+    while (i < s.length) {
+      const ch = s[i];
+      if (ch === '"' || ch === "'") {
+        i = readStringAt(s, i).end;
+        statementStart = false;
+        continue;
+      }
+      if (ch === '<' && !s.startsWith('<<', i)) {
+        i = readIriAt(s, i).end;
+        statementStart = false;
+        continue;
+      }
+      if (ch === '#') {
+        while (i < s.length && s[i] !== '\n' && s[i] !== '\r') i += 1;
+        statementStart = true;
+        continue;
+      }
+      if (statementStart && braceDepth === 0 && bracketDepth === 0 && parenDepth === 0) {
+        const termStart = skipWsAndComments(s, i);
+        const msg = findMessageDirectiveAt(s, termStart);
+        if (msg) {
+          chunks.push(s.slice(start, termStart));
+          start = msg.end;
+          i = msg.end;
+          statementStart = true;
+          sawDelimiter = true;
+          continue;
+        }
+        if (termStart !== i) {
+          i = termStart;
+          continue;
+        }
+      }
+      if (ch === '{') braceDepth += 1;
+      else if (ch === '}' && braceDepth > 0) braceDepth -= 1;
+      else if (ch === '[') bracketDepth += 1;
+      else if (ch === ']' && bracketDepth > 0) bracketDepth -= 1;
+      else if (ch === '(') parenDepth += 1;
+      else if (ch === ')' && parenDepth > 0) parenDepth -= 1;
+
+      if (ch === '.' && braceDepth === 0 && bracketDepth === 0 && parenDepth === 0) statementStart = true;
+      else if (ch === '\n' || ch === '\r') statementStart = true;
+      else if (!/\s/.test(ch)) statementStart = false;
+      i += 1;
+    }
+
+    const tail = s.slice(start);
+    if (!sawDelimiter || !isOnlyWhitespaceAndComments(tail)) chunks.push(tail);
+    return chunks;
+  }
+
+  function normalizeMessageChunk(chunk, messageIndex) {
+    let body = String(chunk || '');
+    if (hasTripleTerms || body.includes('<<')) body = convertTripleTerms(body);
+    if (hasAnnotationSyntax || /(?:^|\s)~\s*(?:<|_:[A-Za-z]|[A-Za-z][A-Za-z0-9_-]*:|\{\|)|\{\|/.test(body)) {
+      body = convertAnnotations(body);
+    }
+    body = normalizeNamedGraphs(body);
+    body = rewriteMessageBlankLabels(body, messageIndex);
+    return body.trim();
+  }
+
+  function messageChunkHasRdf(body) {
+    return !isOnlyWhitespaceAndComments(stripDirectivesAndCommentsForEmptiness(body));
+  }
+
+  function normalizeRdfMessageLog(s) {
+    const withoutVersion = stripVersionDirectives(s);
+    const chunks = splitRdfMessageLog(withoutVersion);
+    const hash = simpleHashText(s);
+    const base = `urn:eyeling:message-log:${hash}`;
+    const stream = `<${base}#stream>`;
+    const envelopeIris = chunks.map((unused, idx) => `<${base}#m${String(idx + 1).padStart(3, '0')}>`);
+    const payloadIris = chunks.map((unused, idx) => `<${base}#m${String(idx + 1).padStart(3, '0')}/payload>`);
+    const out = [];
+
+    out.push(`${stream} ${RDF_TYPE_IRI} ${EYMSG.RDFMessageStream} .`);
+    out.push(`${stream} ${EYMSG.messageCount} "${chunks.length}"^^${XSD_INTEGER_IRI} .`);
+    if (envelopeIris.length) {
+      out.push(`${stream} ${EYMSG.orderedEnvelopes} (${envelopeIris.join(' ')}) .`);
+      out.push(`${stream} ${EYMSG.firstEnvelope} ${envelopeIris[0]} .`);
+      out.push(`${stream} ${EYMSG.lastEnvelope} ${envelopeIris[envelopeIris.length - 1]} .`);
+    }
+
+    for (let idx = 0; idx < chunks.length; idx += 1) {
+      const n = idx + 1;
+      const envelope = envelopeIris[idx];
+      const payload = payloadIris[idx];
+      const body = normalizeMessageChunk(chunks[idx], n);
+      const hasBody = messageChunkHasRdf(body);
+
+      out.push(`${stream} ${EYMSG.envelope} ${envelope} .`);
+      out.push(`${envelope} ${RDF_TYPE_IRI} ${EYMSG.MessageEnvelope} .`);
+      out.push(`${envelope} ${EYMSG.offset} "${n}"^^${XSD_INTEGER_IRI} .`);
+      out.push(`${envelope} ${EYMSG.payloadKind} ${hasBody ? EYMSG.nonEmpty : EYMSG.empty} .`);
+      if (idx + 1 < envelopeIris.length) out.push(`${envelope} ${EYMSG.nextEnvelope} ${envelopeIris[idx + 1]} .`);
+      if (hasBody) {
+        out.push(`${envelope} ${EYMSG.payloadGraph} ${payload} .`);
+        out.push(`${payload} ${LOG_NAME_OF_IRI} {`);
+        out.push(body);
+        out.push(`} .`);
+      }
+    }
+
+    return out.join('\n') + '\n';
+  }
+
+  if (hasMessageVersionDirective) return normalizeRdfMessageLog(text);
+
   if (hasTripleTerms) text = convertTripleTerms(text);
   if (hasAnnotationSyntax) text = convertAnnotations(text);
-  if (hasVersionDirective) text = stripVersionDirectives(text);
-  if (hasVersionDirective || hasNamedGraphCandidate) text = normalizeNamedGraphs(text);
+  if (hasVersionDirective || hasMessageVersionDirective) text = stripVersionDirectives(text);
+  if (hasVersionDirective || hasMessageVersionDirective || hasNamedGraphCandidate) text = normalizeNamedGraphs(text);
   return text;
 }
 

package/examples/deck/rdf-message-flow.md

@@ -0,0 +1,273 @@
+# 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`.
+
+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.
+
+---
+
+## The everyday problem
+
+Many real systems do not receive one big dataset.
+
+They receive a stream of small updates:
+
+- a sensor reading,
+- a command,
+- a status heartbeat,
+- an alert,
+- another sensor reading.
+
+Each update matters as a separate communication event.
+
+If we simply merge everything into one graph, we lose the order and the boundary between messages.
+
+---
+
+## A message is a sealed packet
+
+Think of an RDF Message as a sealed packet of RDF data.
+
+Inside the packet there may be triples or named graphs.
+
+Outside the packet there is the stream order: first message, second message, third message, and so on.
+
+The important idea is:
+
+> The reasoner should know when one message ends and the next one begins.
+
+---
+
+## What an RDF Message Log adds
+
+An RDF Message Log is a replayable record of a message stream.
+
+Instead of saying “subscribe to this live channel”, the file says:
+
+> Here are the messages that arrived, in order.
+
+That makes it useful for examples, tests, audits, debugging, reproducible reasoning, and explanations.
+
+---
+
+## The new syntax in the input file
+
+The input begins with:
+
+```trig
+VERSION "1.2-messages"
+```
+
+That tells Eyeling:
+
+> This file contains message boundaries.
+
+Then each boundary is written as:
+
+```trig
+MESSAGE
+```
+
+So the file can look like this:
+
+```trig
+# message 1 data
+:temperatureFlow :highThreshold 26 .
+_:obs sosa:hasSimpleResult 21 .
+
+MESSAGE
+
+# message 2 data
+_:obs sosa:hasSimpleResult 22 .
+
+MESSAGE
+
+# message 3: empty heartbeat
+MESSAGE
+
+# message 4 data
+_:obs sosa:hasSimpleResult 28 .
+```
+
+---
+
+## What Eyeling does internally
+
+Eyeling does not treat `MESSAGE` as an ordinary RDF term.
+
+It handles it before normal N3 reasoning starts.
+
+Internally, Eyeling turns the log into a replay view:
+
+- one stream resource,
+- one envelope per message,
+- an offset for each envelope,
+- a link to the next envelope,
+- a payload graph for each non-empty message,
+- and an explicit marker for empty messages.
+
+The rules then reason over that replay view.
+
+---
+
+## Why this is better than hand-written envelopes
+
+Before this change, the example input had to describe the stream manually:
+
+- message `:m001`,
+- message `:m002`,
+- payload graph `in:payload001`,
+- next message links,
+- payload kind markers,
+- offsets.
+
+That worked, but it made the example bulky.
+
+It also mixed two concerns:
+
+1. the message-log machinery, and
+2. the domain logic of routing temperature observations.
+
+Now Eyeling handles the message-log machinery.
+
+The N3 file can focus on the logic.
+
+---
+
+## What the temperature-flow example does
+
+The example models a small stream processor.
+
+Messages move through these stages:
+
+1. ingest,
+2. validate,
+3. interpret,
+4. route,
+5. sink.
+
+The stream contains temperature readings and one empty heartbeat.
+
+The rules route normal readings to an archive sink and high readings to an alert sink.
+
+---
+
+## The empty heartbeat matters
+
+One message in the example contains no RDF triples.
+
+That is not an error.
+
+It represents a heartbeat:
+
+> “The stream is still alive, even though there is no new observation payload.”
+
+Eyeling still creates an envelope for it.
+
+That means the empty message keeps its place in the ordered replay.
+
+---
+
+## Blank nodes stay message-local
+
+The input deliberately reuses the same blank-node label in several messages:
+
+```trig
+_:obs sosa:hasSimpleResult 21 .
+
+MESSAGE
+
+_:obs sosa:hasSimpleResult 22 .
+```
+
+That does not mean both messages talk about the same blank node.
+
+In a message log, blank-node labels are scoped to the message.
+
+Eyeling rewrites them internally so each message gets its own blank nodes.
+
+---
+
+## How the N3 rules see the replay
+
+The N3 rules do not see `MESSAGE` directly.
+
+They see Eyeling’s replay vocabulary, `eymsg:`.
+
+For example, a rule can ask:
+
+```n3
+?Stream a eymsg:RDFMessageStream;
+  eymsg:firstEnvelope ?Envelope.
+```
+
+Another rule can inspect a payload:
+
+```n3
+?Envelope eymsg:payloadGraph ?Payload.
+?Payload log:nameOf ?PayloadContext.
+?PayloadContext log:includes {
+  ?Observation sosa:hasSimpleResult ?Result.
+}.
+```
+
+That keeps each message payload inside its own context.
+
+---
+
+## Back pressure in one sentence
+
+The example releases only the first envelope at the start.
+
+Each envelope must reach the sink before the next envelope is released.
+
+That gives a simple form of ordered replay or back pressure:
+
+> process this message, then release the next one.
+
+---
+
+## What the final answer says
+
+When the example succeeds, Eyeling reports that five parser-replayed envelopes moved through the flow.
+
+With a threshold of 26:
+
+- 21 is archived,
+- 22 is archived,
+- the empty heartbeat is accepted,
+- 28 becomes an alert,
+- 29 becomes an alert.
+
+The important part is not only the routing result.
+
+The important part is that the result was derived while preserving message boundaries.
+
+---
+
+## Why a wide audience should care
+
+This pattern is useful wherever data arrives over time:
+
+- sensors,
+- event logs,
+- audit trails,
+- clinical systems,
+- energy systems,
+- pub/sub channels,
+- digital twins,
+- provenance streams.
+
+You can replay the stream, reason over each message atomically, and explain what happened without flattening the whole history into one graph.
+
+---
+
+## The takeaway
+
+`MESSAGE` is the boundary.
+
+Eyeling turns those boundaries into ordered replay envelopes.
+
+The N3 rules consume the replay and focus on the domain logic.
+
+That makes the example shorter, clearer, and closer to how a real pub/sub channel would be processed.