eyeling 1.34.0 → 1.34.2

package/README.md

@@ -774,18 +774,19 @@ The Alma RDF Message Log example intentionally keeps the message log as a URL, b
 
 ## Built-ins
 
-Eyeling implements SWAP-style built-ins for the N3 engine across these namespaces. The authoritative machine-readable catalog is [`eyeling-builtins.ttl`](eyeling-builtins.ttl); this README lists the public names so users do not need to infer support from examples.
-
-| Namespace | Built-ins |
-|---|---|
-| `crypto:` | `sha`, `md5`, `sha256`, `sha512` |
-| `math:` | `equalTo`, `notEqualTo`, `greaterThan`, `lessThan`, `notLessThan`, `notGreaterThan`, `sum`, `product`, `difference`, `quotient`, `integerQuotient`, `remainder`, `rounded`, `exponentiation`, `absoluteValue`, `acos`, `asin`, `atan`, `sin`, `cos`, `tan`, `sinh`, `cosh`, `tanh`, `degrees`, `negation` |
-| `time:` | `day`, `hour`, `minute`, `month`, `second`, `timeZone`, `year`, `localTime` |
-| `list:` | `append`, `first`, `rest`, `iterate`, `last`, `memberAt`, `remove`, `member`, `in`, `length`, `notMember`, `reverse`, `sort`, `map`, `firstRest` |
-| `rdf:` | `first`, `rest` |
-| `log:` | `equalTo`, `notEqualTo`, `conjunction`, `conclusion`, `content`, `semantics`, `semanticsOrError`, `parsedAsN3`, `rawType`, `dtlit`, `langlit`, `implies`, `impliedBy`, `query`, `includes`, `notIncludes`, `collectAllIn`, `forAllIn`, `skolem`, `uri`, `trace`, `outputString` |
-| `string:` | `concatenation`, `contains`, `containsIgnoringCase`, `endsWith`, `startsWith`, `equalIgnoringCase`, `notEqualIgnoringCase`, `greaterThan`, `lessThan`, `notGreaterThan`, `notLessThan`, `matches`, `notMatches`, `replace`, `scrape`, `format`, `length`, `charAt`, `setCharAt` |
-| `dt:` | `datatype`, `lexicalForm`, `language`, `validForDatatype`, `invalidForDatatype`, `sameValueAs`, `differentValueFrom`, `canonicalLiteral` |
+Eyeling implements **104 public SWAP-style built-in predicates** for the N3 engine across these namespaces. The authoritative machine-readable catalog is [`eyeling-builtins.ttl`](eyeling-builtins.ttl); this README lists the public names so users do not need to infer support from examples or internal dispatch code.
+
+| Namespace | Count | Built-ins |
+|---|---:|---|
+| `crypto:` | 4 | `sha`, `md5`, `sha256`, `sha512` |
+| `math:` | 26 | `equalTo`, `notEqualTo`, `greaterThan`, `lessThan`, `notLessThan`, `notGreaterThan`, `sum`, `product`, `difference`, `quotient`, `integerQuotient`, `remainder`, `rounded`, `exponentiation`, `absoluteValue`, `acos`, `asin`, `atan`, `sin`, `cos`, `tan`, `sinh`, `cosh`, `tanh`, `degrees`, `negation` |
+| `time:` | 8 | `day`, `hour`, `minute`, `month`, `second`, `timeZone`, `year`, `localTime` |
+| `list:` | 15 | `append`, `first`, `rest`, `iterate`, `last`, `memberAt`, `remove`, `member`, `in`, `length`, `notMember`, `reverse`, `sort`, `map`, `firstRest` |
+| `rdf:` | 2 | `first`, `rest` |
+| `log:` | 22 | `equalTo`, `notEqualTo`, `conjunction`, `conclusion`, `content`, `semantics`, `semanticsOrError`, `parsedAsN3`, `rawType`, `dtlit`, `langlit`, `implies`, `impliedBy`, `query`, `includes`, `notIncludes`, `collectAllIn`, `forAllIn`, `skolem`, `uri`, `trace`, `outputString` |
+| `string:` | 19 | `concatenation`, `contains`, `containsIgnoringCase`, `endsWith`, `startsWith`, `equalIgnoringCase`, `notEqualIgnoringCase`, `greaterThan`, `lessThan`, `notGreaterThan`, `notLessThan`, `matches`, `notMatches`, `replace`, `scrape`, `format`, `length`, `charAt`, `setCharAt` |
+| `dt:` | 8 | `datatype`, `lexicalForm`, `language`, `validForDatatype`, `invalidForDatatype`, `sameValueAs`, `differentValueFrom`, `canonicalLiteral` |
+| **Total** | **104** |  |
 
 The catalog marks each built-in with a coarse kind: `ex:Test`, `ex:Function`, `ex:Relation`, `ex:Generator`, `ex:IO`, `ex:Meta`, or `ex:SideEffect`.
 
@@ -818,20 +819,21 @@ 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:
-
-| 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`, `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` |
-| Context terms | `holds/2`, `holds/3` |
-| Search and optimization helpers | `n_queens/2`, `weighted_hamiltonian_cycle/4`, `weighted_hamiltonian_path/4`, `hamiltonian_cycle/3`, `fixed_length_cycle/4`, `bounded_path/5`, `cnf_model/3`, `qm_prime_implicants/4`, `qm_minimal_cover/4` |
-| Numeric extension helpers | `extended_gcd/5`, `collatz_trajectory/2`, `kaprekar_steps/2`, `goldbach_pair/3` |
-| Matrix helpers | `matrix_sum/2`, `matrix_multiply/2`, `cholesky_decomposition/2`, `determinant/2`, `matrix_inv_triang/2`, `matrix_inversion/2` |
+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 | Count | Built-ins |
+|---|---:|---|
+| Core and host | 4 | `eq/2`, `neq/2`, `local_time/1`, `difference/3` |
+| Arithmetic and comparison | 21 | `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 | 5 | `str_concat/3`, `contains/2`, `matches/2`, `matches/3`, `not_matches/2` |
+| Lists | 10 | `append/3`, `nth0/3`, `set_nth0/4`, `rest/2`, `member/2`, `select/3`, `not_member/2`, `reverse/2`, `length/2`, `sort/2` |
+| Aggregation | 5 | `findall/3`, `countall/2`, `sumall/3`, `aggregate_min/5`, `aggregate_max/5` |
+| Control | 2 | `not/1`, `once/1` |
+| Context terms | 2 | `holds/2`, `holds/3` |
+| Search and optimization helpers | 9 | `n_queens/2`, `weighted_hamiltonian_cycle/4`, `weighted_hamiltonian_path/4`, `hamiltonian_cycle/3`, `fixed_length_cycle/4`, `bounded_path/5`, `cnf_model/3`, `qm_prime_implicants/4`, `qm_minimal_cover/4` |
+| Numeric extension helpers | 4 | `extended_gcd/5`, `collatz_trajectory/2`, `kaprekar_steps/2`, `goldbach_pair/3` |
+| Matrix helpers | 6 | `matrix_sum/2`, `matrix_multiply/2`, `cholesky_decomposition/2`, `determinant/2`, `matrix_inv_triang/2`, `matrix_inversion/2` |
+| **Total** | **68** |  |
 
 ## Custom built-ins
 
@@ -1128,6 +1130,7 @@ The repository contains more than two hundred N3 examples under `examples/`, eye
 | `examples/string-builtins-tests.n3` | String built-ins. |
 | `examples/math-builtins-tests.n3` | Numeric built-ins. |
 | `examples/rdf-messages.n3` | RDF Message Log replay. |
+| `examples/context-schema-audit.n3` | Quoted-context schema validation with `log:includes` and list arity checks. |
 
 ### Running all examples through tests
 

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.
 
@@ -300,6 +300,8 @@ Use `holds/2` when you want to match the member term directly, for example `name
 
 `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.
 
+The N3 counterpart of the context schema audit lives at [`examples/context-schema-audit.n3`](../examples/context-schema-audit.n3) with golden output in [`examples/output/context-schema-audit.md`](../examples/output/context-schema-audit.md).
+
 
 ## Example catalog
 

package/docs/eyelang-language-reference.md

@@ -450,6 +450,8 @@ The first goal can yield `holds((name(alice, "Alice"), knows(alice, bob)), name(
 
 `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).
 
+The N3 example [`context-schema-audit.n3`](../examples/context-schema-audit.n3) shows the same idea in quoted graph form: members are encoded as predicates with RDF-list argument objects, then `log:includes` and `list:length` expose `Name + Arity` for schema checking.
+
 ### 9.10 Search control
 
 | Built-in | Meaning |

package/examples/context-schema-audit.n3

@@ -0,0 +1,72 @@
+# Context schema audit
+#
+# This is the N3 counterpart of the eyelang context-schema-audit example.  Each
+# message carries a quoted context graph whose members encode an event name as
+# the predicate and its arguments as an RDF list.  A generic rule uses
+# log:includes to inspect those quoted contexts, list:length to compute arity,
+# and schema rules to flag unexpected or wrong-arity members.
+
+@prefix log: <http://www.w3.org/2000/10/swap/log#>.
+@prefix list: <http://www.w3.org/2000/10/swap/list#>.
+@prefix math: <http://www.w3.org/2000/10/swap/math#>.
+@prefix : <http://example.org/#>.
+
+:msg_ok :context {
+  :entry :heartbeat ().
+  :entry :source (:sensor17).
+  :entry :temperature (:sensor17 38).
+  :entry :gps (:sensor17 51 4).
+  :entry :signature (:sensor17 :sha256 "9f86d081" "2026-06-18T09:30:00Z").
+}.
+
+:msg_bad :context {
+  :entry :heartbeat ().
+  :entry :source (:sensor18).
+  :entry :temperature (:sensor18 99).
+  :entry :gps (:sensor18 51).
+  :entry :tampered (:sensor18).
+}.
+
+:heartbeat :allowedArity 0.
+:source :allowedArity 1.
+:temperature :allowedArity 2.
+:gps :allowedArity 3.
+:signature :allowedArity 4.
+
+{
+  ?Message :context ?Context.
+  ?Context log:includes { :entry ?Name ?Args }.
+  ?Args list:length ?Arity.
+}
+=>
+{
+  ?Message :contextShape (?Name ?Arity).
+}.
+
+{
+  ?Message :contextShape (?Name ?Arity).
+  ?Name :allowedArity ?AllowedArity.
+  ?Arity math:notEqualTo ?AllowedArity.
+}
+=>
+{
+  ?Message :schemaViolation (?Name ?Arity).
+}.
+
+{
+  ?Message :contextShape (?Name ?Arity).
+  1 log:notIncludes { ?Name :allowedArity ?AnyArity. }.
+}
+=>
+{
+  ?Message :schemaViolation (?Name ?Arity).
+}.
+
+{
+  :msg_bad :schemaViolation (:gps 2).
+  :msg_bad :schemaViolation (:tampered 1).
+}
+=>
+{
+  :report log:outputString "# Context schema audit\n\n## Source files\n\n- [N3 rules](../context-schema-audit.n3)\n\n## Entailment\nThe audit inspects quoted message contexts and finds two schema violations in `msg_bad`: `gps/2` should have arity 3, and `tampered/1` is not an allowed context member.\n\n## Explanation\nEach context member is encoded as a quoted triple whose predicate is the member name and whose object is the argument list. The generic audit rule uses `log:includes` to bind the member name and argument list, then `list:length` to compute the arity. Allowed shapes are declared once as `:allowedArity` facts, so the same rule can validate zero-, unary-, binary-, ternary-, and four-argument members without writing a separate rule per predicate.\n".
+}.

package/examples/output/context-schema-audit.md

@@ -0,0 +1,11 @@
+# Context schema audit  
+
+## Source files  
+
+- [N3 rules](../context-schema-audit.n3)  
+
+## Entailment  
+The audit inspects quoted message contexts and finds two schema violations in `msg_bad`: `gps/2` should have arity 3, and `tampered/1` is not an allowed context member.  
+
+## Explanation  
+Each context member is encoded as a quoted triple whose predicate is the member name and whose object is the argument list. The generic audit rule uses `log:includes` to bind the member name and argument list, then `list:length` to compute the arity. Allowed shapes are declared once as `:allowedArity` facts, so the same rule can validate zero-, unary-, binary-, ternary-, and four-argument members without writing a separate rule per predicate.  

package/package.json

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

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);