eyeling 1.33.11 → 1.34.1

package/README.md

@@ -818,13 +818,13 @@ Formula-aware built-ins make Eyeling useful for meta-reasoning. `log:includes`,
 
 ### eyelang built-ins
 
-The eyelang engine has its own built-in registry under `lib/eyelang/builtins/`. These are separate from the N3 namespaces above and are called as ordinary eyelang predicates. See the [eyelang language reference](docs/eyelang-language-reference.md#9-standard-built-in-predicates) for the portable profile. The bundled implementation currently registers:
+The eyelang engine has its own built-in registry under `lib/eyelang/builtins/`. These are separate from the N3 namespaces above and are called as ordinary eyelang predicates. See the [eyelang language reference](docs/eyelang-language-reference.md#9-standard-built-in-predicates) for the portable profile. The bundled implementation currently registers 68 name/arity entries across 66 predicate names:
 
 | Family | Built-ins |
 |---|---|
 | 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

@@ -261,7 +261,7 @@ best(Cycle, Cost) :-
   weighted_hamiltonian_cycle(edge, Cities, Cycle, Cost).
 ```
 
-The reusable search and numeric helpers include `n_queens/2`, Hamiltonian path/cycle helpers, `bounded_path/5`, `cnf_model/3`, Quine-McCluskey helpers, number-theory helpers such as `extended_gcd/5`, and matrix helpers such as `matrix_multiply/2`. These helpers are extension builtins of this implementation; [the eyelang language reference](eyelang-language-reference.md) defines the portable core and standard builtin profile.
+The reusable search and numeric helpers include `n_queens/2`, Hamiltonian path/cycle helpers, `bounded_path/5`, `cnf_model/3`, Quine-McCluskey helpers, number-theory helpers such as `extended_gcd/5`, and matrix helpers such as `matrix_multiply/2`. These helpers are extension builtins of this implementation; [the eyelang language reference](eyelang-language-reference.md) defines the portable core and standard builtin profile. The complete bundled implementation list is kept in the top-level [README built-ins section](../README.md#built-ins-1), and the regression suite checks that table against the actual runtime registry.
 
 To add a builtin, create or extend a module with `register(registry)` and call `registry.add(name, arity, handler, options)`. The default registry is assembled in [`lib/eyelang/builtins/registry.js`](../lib/eyelang/builtins/registry.js). Builtins that are only safe for specific argument modes should provide a `ready` predicate and `fallbackWhenNotReady: true`, so user-defined clauses remain visible until the builtin is applicable.
 
@@ -298,6 +298,8 @@ 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. 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
 
@@ -409,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

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/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.11",
+  "version": "1.34.1",
   "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").

package/test/eyelang/run-regression.mjs

@@ -196,6 +196,18 @@ why(
         assertEqual(readmeExamples.join('\n'), examples.join('\n'), 'README example catalog');
       },
     },
+    {
+      name: 'README mirrors the eyelang builtin registry',
+      run: () => {
+        const actual = registeredBuiltinNames();
+        const documented = readmeBuiltinNames();
+        assertEqual(documented.join('\n'), actual.join('\n'), 'README builtin catalog');
+
+        const { entries, names } = readmeBuiltinSummary();
+        assertEqual(entries, actual.length, 'README builtin entry count');
+        assertEqual(names, new Set(actual.map((item) => item.split('/')[0])).size, 'README builtin name count');
+      },
+    },
     {
       name: 'stdin input is accepted',
       run: () => {
@@ -499,6 +511,27 @@ function readmeCatalogExampleNames() {
     .sort();
 }
 
+function registeredBuiltinNames() {
+  return [...createDefaultRegistry().defs.keys()].sort();
+}
+
+function readmeBuiltinNames() {
+  const readme = fs.readFileSync(path.join(packageRoot, 'README.md'), 'utf8');
+  const section = between(readme, '### eyelang built-ins', '## Custom built-ins');
+  return [...section.matchAll(/`([A-Za-z_][A-Za-z0-9_]*)\/(\d+)`/g)]
+    .map((match) => `${match[1]}/${match[2]}`)
+    .filter((name, index, names) => names.indexOf(name) === index)
+    .sort();
+}
+
+function readmeBuiltinSummary() {
+  const readme = fs.readFileSync(path.join(packageRoot, 'README.md'), 'utf8');
+  const section = between(readme, '### eyelang built-ins', '## Custom built-ins');
+  const match = section.match(/currently registers (\d+) name\/arity entries across (\d+) predicate names/);
+  if (match == null) throw new Error('README builtin summary not found');
+  return { entries: Number(match[1]), names: Number(match[2]) };
+}
+
 function playgroundExampleNames() {
   const html = fs.readFileSync(path.join(root, 'playground.html'), 'utf8');
   const match = html.match(/const EXAMPLES = \[(.*?)\];/s);