eyeling 1.33.10 → 1.34.0

package/README.md

@@ -824,7 +824,7 @@ The eyelang engine has its own built-in registry under `lib/eyelang/builtins/`.
 |---|---|
 | Core and host | `eq/2`, `neq/2`, `local_time/1`, `difference/3` |
 | Arithmetic and comparison | `neg/2`, `abs/2`, `sin/2`, `cos/2`, `asin/2`, `acos/2`, `rounded/2`, `log/2`, `add/3`, `sub/3`, `mul/3`, `div/3`, `mod/3`, `min/3`, `pow/3`, `lt/2`, `gt/2`, `le/2`, `ge/2`, `between/3`, `smallest_divisor_from/3` |
-| Strings | `str_concat/3`, `contains/2`, `matches/2`, `not_matches/2` |
+| Strings | `str_concat/3`, `contains/2`, `matches/2`, `matches/3`, `not_matches/2` |
 | Lists | `append/3`, `nth0/3`, `set_nth0/4`, `rest/2`, `member/2`, `select/3`, `not_member/2`, `reverse/2`, `length/2`, `sort/2` |
 | Aggregation | `findall/3`, `countall/2`, `sumall/3`, `aggregate_min/5`, `aggregate_max/5` |
 | Control | `not/1`, `once/1` |

package/docs/eyelang-guide.md

@@ -296,7 +296,9 @@ holds((name(alice, "Alice"), knows(alice, bob)), name(S, O)).
 holds((ready, name(alice, "Alice"), route(alice, bob, 7)), Name, Args).
 ```
 
-Use `holds/2` when you want to match the member term directly, for example `name(S, O)`, `route(A, B, Cost)`, or `edge(A, arc(B, Cost))`. Use `holds/3` when you need the predicate name and argument list as data: it exposes any-arity member as atom constant `Name` plus a proper list `Args`, so zero-, binary-, and ternary members appear as `ready/0`, `name/2`, and `route/3` shapes without a special binary predicate. These utilities are useful for quoted context data, but they do not make those context members true in the ambient program.
+Use `holds/2` when you want to match the member term directly, for example `name(S, O)`, `route(A, B, Cost)`, or `edge(A, arc(B, Cost))`. Use `holds/3` when you need the predicate name and argument list as data: it exposes any-arity member as atom constant `Name` plus a proper list `Args`, so zero-, binary-, and ternary members appear as `ready/0`, `name/2`, and `route/3` shapes without a special binary predicate. These utilities are useful for quoted context data, but they do not make those context members true in the ambient program. The [`context-schema-audit.pl`](../examples/eyelang/context-schema-audit.pl) example shows a case that really needs `holds/3`: it audits heterogeneous message contexts by extracting every member as `Name + Args`, computing each arity, and checking the resulting shape against a schema without knowing the predicate names in advance.
+
+`matches/3` can create context data from named regular-expression captures, which is useful when text logs or messages need to become facts before later rules inspect them with `holds/2` or `holds/3`. See [`observability-log-correlation.pl`](../examples/eyelang/observability-log-correlation.pl) for a complete log-correlation example.
 
 
 ## Example catalog
@@ -335,6 +337,7 @@ The repository includes examples for recursion, graph reachability, finite searc
 | [`complex.pl`](../examples/eyelang/complex.pl) | Performs arithmetic on complex pairs. | [`output/complex.pl`](../examples/eyelang/output/complex.pl) |
 | [`composition-of-injective-functions-is-injective.pl`](../examples/eyelang/composition-of-injective-functions-is-injective.pl) | Encodes composition and injectivity of finite functions. | [`output/composition-of-injective-functions-is-injective.pl`](../examples/eyelang/output/composition-of-injective-functions-is-injective.pl) |
 | [`context-association.pl`](../examples/eyelang/context-association.pl) | Associates named contexts with their contents. | [`output/context-association.pl`](../examples/eyelang/output/context-association.pl) |
+| [`context-schema-audit.pl`](../examples/eyelang/context-schema-audit.pl) | Audits mixed-arity context members with `holds/3`. | [`output/context-schema-audit.pl`](../examples/eyelang/output/context-schema-audit.pl) |
 | [`control-system.pl`](../examples/eyelang/control-system.pl) | Evaluates control-system measurements and targets. | [`output/control-system.pl`](../examples/eyelang/output/control-system.pl) |
 | [`cyclic-path.pl`](../examples/eyelang/cyclic-path.pl) | Computes paths in a cyclic graph. | [`output/cyclic-path.pl`](../examples/eyelang/output/cyclic-path.pl) |
 | [`d3-group.pl`](../examples/eyelang/d3-group.pl) | Enumerates subgroups of the D3 group. | [`output/d3-group.pl`](../examples/eyelang/output/d3-group.pl) |
@@ -408,6 +411,7 @@ The repository includes examples for recursion, graph reachability, finite searc
 | [`network-sla.pl`](../examples/eyelang/network-sla.pl) | Checks network path SLA compliance. | [`output/network-sla.pl`](../examples/eyelang/output/network-sla.pl) |
 | [`newton-raphson.pl`](../examples/eyelang/newton-raphson.pl) | Finds roots by Newton-Raphson iteration. | [`output/newton-raphson.pl`](../examples/eyelang/output/newton-raphson.pl) |
 | [`nixon-diamond.pl`](../examples/eyelang/nixon-diamond.pl) | Reports the classic Nixon-diamond conflict. | [`output/nixon-diamond.pl`](../examples/eyelang/output/nixon-diamond.pl) |
+| [`observability-log-correlation.pl`](../examples/eyelang/observability-log-correlation.pl) | Extracts named regex captures from observability logs and correlates events by trace id. | [`output/observability-log-correlation.pl`](../examples/eyelang/output/observability-log-correlation.pl) |
 | [`odrl-dpv-fpv-trust-flow.pl`](../examples/eyelang/odrl-dpv-fpv-trust-flow.pl) | Decides ODRL/DPV data flows with local FPV trust gates. | [`output/odrl-dpv-fpv-trust-flow.pl`](../examples/eyelang/output/odrl-dpv-fpv-trust-flow.pl) |
 | [`odrl-dpv-healthcare-risk-ranked.pl`](../examples/eyelang/odrl-dpv-healthcare-risk-ranked.pl) | Ranks healthcare policy risks and mitigations. | [`output/odrl-dpv-healthcare-risk-ranked.pl`](../examples/eyelang/output/odrl-dpv-healthcare-risk-ranked.pl) |
 | [`odrl-dpv-risk-ranked.pl`](../examples/eyelang/odrl-dpv-risk-ranked.pl) | Ranks data-policy risks and mitigations. | [`output/odrl-dpv-risk-ranked.pl`](../examples/eyelang/output/odrl-dpv-risk-ranked.pl) |

package/docs/eyelang-language-reference.md

@@ -402,6 +402,7 @@ Comparisons interpret numeric-looking terms numerically. Other scalar terms are
 | `str_concat(A, B, C)` | String concatenation. |
 | `contains(Text, Needle)` | Text contains `Needle`. |
 | `matches(Text, Pattern)` | Text matches a simple implementation regex/search pattern. |
+| `matches(Text, Pattern, Context)` | Text matches a JavaScript regular expression with named capture groups; `Context` is a comma context containing one unary term per matched capture group. |
 | `not_matches(Text, Pattern)` | Negation of `matches/2`. |
 
 ### 9.7 Lists
@@ -447,6 +448,8 @@ holds((ready, name(alice, "Alice"), route(alice, bob, 7)), Name, Args).
 
 The first goal can yield `holds((name(alice, "Alice"), knows(alice, bob)), name(alice, "Alice")).` The second can yield `holds((ready, name(alice, "Alice"), route(alice, bob, 7)), ready, []).`, `holds((ready, name(alice, "Alice"), route(alice, bob, 7)), name, [alice, "Alice"]).`, and `holds((ready, name(alice, "Alice"), route(alice, bob, 7)), route, [alice, bob, 7]).`
 
+`holds/3` is the appropriate form for schema-style introspection because it exposes the predicate name and all arguments without assuming a fixed arity. For example, a single rule can inspect `heartbeat`, `source(sensor17)`, `temperature(sensor17, 38)`, and `signature(sensor17, sha256, Hash, Time)` as `heartbeat/0`, `source/1`, `temperature/2`, and `signature/4`; see [`context-schema-audit.pl`](../examples/eyelang/context-schema-audit.pl).
+
 ### 9.10 Search control
 
 | Built-in | Meaning |

package/examples/eyelang/context-schema-audit.pl

@@ -0,0 +1,46 @@
+% Context schema audit.
+%
+% This example needs holds/3 rather than holds/2 because the audit rule does
+% not know the predicate names or arities in advance.  It inspects a whole
+% context as data, extracts each member as Name + Args, computes the arity, and
+% checks that shape against an allowed schema.
+
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
+materialize(context_shape, 3).
+materialize(schema_violation, 3).
+
+% Program structure: each message carries heterogeneous context data.  The
+% members deliberately use different arities: heartbeat/0, source/1,
+% temperature/2, gps/3, and signature/4.
+message_context(msg_ok, (
+  heartbeat,
+  source(sensor17),
+  temperature(sensor17, 38),
+  gps(sensor17, 51, 4),
+  signature(sensor17, sha256, "9f86d081", "2026-06-18T09:30:00Z")
+)).
+
+message_context(msg_bad, (
+  heartbeat,
+  source(sensor18),
+  temperature(sensor18, 99),
+  gps(sensor18, 51),
+  tampered(sensor18)
+)).
+
+allowed_shape(heartbeat, 0).
+allowed_shape(source, 1).
+allowed_shape(temperature, 2).
+allowed_shape(gps, 3).
+allowed_shape(signature, 4).
+
+% Derivation rules: holds/3 exposes arbitrary context members as predicate name
+% plus argument list, so one generic rule can audit mixed-arity data.
+context_shape(Message, Name, Arity) :-
+  message_context(Message, Context),
+  holds(Context, Name, Args),
+  length(Args, Arity).
+
+schema_violation(Message, Name, Arity) :-
+  context_shape(Message, Name, Arity),
+  not(allowed_shape(Name, Arity)).

package/examples/eyelang/observability-log-correlation.pl

@@ -0,0 +1,34 @@
+% Parse unstructured service logs with named regex captures, then reason over
+% the extracted context to correlate events that share a trace id.
+materialize(parsed_event, 5).
+materialize(captured_field, 3).
+materialize(trace_alert, 3).
+
+log_pattern("^ts=(?<ts>\\S+) level=(?<level>\\w+) event=(?<event>\\w+) user=(?<user>\\w+) ip=(?<ip>\\S+) traceparent=00-(?<trace_id>[0-9a-f]{32})-(?<span_id>[0-9a-f]{16})-(?<flags>[0-9a-f]{2})$").
+
+raw_log(l1, "ts=2026-06-18T10:00:00Z level=warn event=login_failed user=alice ip=203.0.113.9 traceparent=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01").
+raw_log(l2, "ts=2026-06-18T10:00:03Z level=error event=payment_denied user=alice ip=203.0.113.9 traceparent=00-4bf92f3577b34da6a3ce929d0e0e4736-aaf067aa0ba90000-01").
+raw_log(l3, "ts=2026-06-18T10:01:12Z level=info event=login_success user=bob ip=198.51.100.4 traceparent=00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01").
+raw_log(noise, "healthcheck ok").
+
+parsed(Log, Context) :-
+  raw_log(Log, Text),
+  log_pattern(Pattern),
+  matches(Text, Pattern, Context).
+
+% holds/3 lets one generic rule project every named capture as field data.
+captured_field(Log, Name, Value) :-
+  parsed(Log, Context),
+  holds(Context, Name, [Value]).
+
+parsed_event(Log, Event, User, Ip, TraceId) :-
+  parsed(Log, Context),
+  holds(Context, event(Event)),
+  holds(Context, user(User)),
+  holds(Context, ip(Ip)),
+  holds(Context, trace_id(TraceId)).
+
+trace_alert(User, TraceId, Ip) :-
+  parsed_event(LoginLog, "login_failed", User, Ip, TraceId),
+  parsed_event(PaymentLog, "payment_denied", User, Ip, TraceId),
+  neq(LoginLog, PaymentLog).

package/examples/eyelang/output/context-schema-audit.pl

@@ -0,0 +1,12 @@
+context_shape(msg_ok, heartbeat, 0).
+context_shape(msg_ok, source, 1).
+context_shape(msg_ok, temperature, 2).
+context_shape(msg_ok, gps, 3).
+context_shape(msg_ok, signature, 4).
+context_shape(msg_bad, heartbeat, 0).
+context_shape(msg_bad, source, 1).
+context_shape(msg_bad, temperature, 2).
+context_shape(msg_bad, gps, 2).
+context_shape(msg_bad, tampered, 1).
+schema_violation(msg_bad, gps, 2).
+schema_violation(msg_bad, tampered, 1).

package/examples/eyelang/output/observability-log-correlation.pl

@@ -0,0 +1,28 @@
+captured_field(l1, ts, "2026-06-18T10:00:00Z").
+captured_field(l1, level, "warn").
+captured_field(l1, event, "login_failed").
+captured_field(l1, user, "alice").
+captured_field(l1, ip, "203.0.113.9").
+captured_field(l1, trace_id, "4bf92f3577b34da6a3ce929d0e0e4736").
+captured_field(l1, span_id, "00f067aa0ba902b7").
+captured_field(l1, flags, "01").
+captured_field(l2, ts, "2026-06-18T10:00:03Z").
+captured_field(l2, level, "error").
+captured_field(l2, event, "payment_denied").
+captured_field(l2, user, "alice").
+captured_field(l2, ip, "203.0.113.9").
+captured_field(l2, trace_id, "4bf92f3577b34da6a3ce929d0e0e4736").
+captured_field(l2, span_id, "aaf067aa0ba90000").
+captured_field(l2, flags, "01").
+captured_field(l3, ts, "2026-06-18T10:01:12Z").
+captured_field(l3, level, "info").
+captured_field(l3, event, "login_success").
+captured_field(l3, user, "bob").
+captured_field(l3, ip, "198.51.100.4").
+captured_field(l3, trace_id, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").
+captured_field(l3, span_id, "bbbbbbbbbbbbbbbb").
+captured_field(l3, flags, "01").
+parsed_event(l1, "login_failed", "alice", "203.0.113.9", "4bf92f3577b34da6a3ce929d0e0e4736").
+parsed_event(l2, "payment_denied", "alice", "203.0.113.9", "4bf92f3577b34da6a3ce929d0e0e4736").
+parsed_event(l3, "login_success", "bob", "198.51.100.4", "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").
+trace_alert("alice", "4bf92f3577b34da6a3ce929d0e0e4736", "203.0.113.9").

package/lib/eyelang/builtins/strings.js

@@ -1,11 +1,12 @@
 // String builtins.
 // They mostly project from already-ground terms to avoid guessing string domains.
-import { lexicalValue, stringTerm, unify } from '../term.js';
+import { compound, lexicalValue, stringTerm, unify } from '../term.js';
 
 export const stringBuiltins = {
   register(registry) {
     registry.add('str_concat', 3, concat, { deterministic: true });
     for (const name of ['contains', 'matches', 'not_matches']) registry.add(name, 2, contains(name), { deterministic: true });
+    registry.add('matches', 3, matchCaptures, { deterministic: true });
   }
 };
 
@@ -32,6 +33,38 @@ function contains(name) {
   };
 }
 
+function* matchCaptures({ goal, env }) {
+  const text = lexicalValue(goal.args[0], env);
+  const pattern = lexicalValue(goal.args[1], env);
+  if (text == null || pattern == null) return;
+
+  let match;
+  try {
+    match = new RegExp(pattern).exec(text);
+  } catch (_) {
+    return;
+  }
+  if (!match?.groups) return;
+
+  const context = contextFromGroups(match.groups);
+  if (context == null) return;
+
+  const next = env.clone();
+  if (unify(goal.args[2], context, next)) yield next;
+}
+
+function contextFromGroups(groups) {
+  const terms = [];
+  for (const [name, value] of Object.entries(groups)) {
+    if (value !== undefined) terms.push(compound(name, [stringTerm(value)]));
+  }
+  if (terms.length === 0) return null;
+
+  let context = terms[terms.length - 1];
+  for (let i = terms.length - 2; i >= 0; i--) context = compound(',', [terms[i], context]);
+  return context;
+}
+
 function simpleAlternationMatch(haystack, pattern) {
   return pattern.split('|').some((part) => part === '' || haystack.includes(part));
 }

package/package.json

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

package/test/eyelang/conformance/cases/extension/044_matches_named_captures.pl

@@ -0,0 +1,13 @@
+% Reference 9.6: matches/3 extracts named regular-expression captures into a context.
+materialize(answer, 3).
+
+line("event=login_failed user=alice trace=4bf92f3577b34da6a3ce929d0e0e4736").
+pattern("^event=(?<event>\\w+) user=(?<user>\\w+) trace=(?<trace_id>[0-9a-f]{32})$").
+
+answer(User, Event, TraceId) :-
+  line(Text),
+  pattern(Pattern),
+  matches(Text, Pattern, Context),
+  holds(Context, event(Event)),
+  holds(Context, user(User)),
+  holds(Context, trace_id(TraceId)).

package/test/eyelang/conformance/expected/extension/044_matches_named_captures.out

@@ -0,0 +1 @@
+answer("alice", "login_failed", "4bf92f3577b34da6a3ce929d0e0e4736").