eyeling 1.19.1 → 1.19.3

package/HANDBOOK.md

@@ -2085,9 +2085,24 @@ const { reason } = require('eyeling');
 const out = reason({ builtinModules: ['./hello-builtin.js'] }, n3Text);
 ```
 
+### 16.2.1 Stability rule for `--builtin`
+
+Eyeling keeps `--builtin` simple.
+
+There is one small helper API passed into builtin modules. That helper object is frozen, its key set is regression-tested, and builtin modules must use one of the documented export forms.
+
+In practice, this means:
+
+- builtin module loading accepts only the documented export forms
+- the helper API exposed by `__buildBuiltinRegistrationApi()` has a fixed key set
+- builtin handlers should return an array of substitution objects
+- accidental helper drift is caught by `test/builtin-contract.test.js`
+
+This is only meant to stop silent breakage. It is **not** a promise that Eyeling can never change the builtin API. If the helper surface ever needs to change, that change should be deliberate, documented, and called out in release notes.
+
 ### 16.3 What a builtin module may export
 
-Eyeling accepts three module shapes.
+Eyeling accepts these stable module shapes.
 
 #### A function export
 
@@ -2124,23 +2139,52 @@ module.exports = {
 };
 ```
 
+#### An object with `.builtins`
+
+```js
+module.exports = {
+  builtins: {
+    'http://example.org/custom#ok': ({ subst }) => [subst],
+  },
+};
+```
+
+#### An object with `.default` as a plain object map
+
+This is mainly an ESM/transpiler compatibility form.
+
+```js
+module.exports = {
+  default: {
+    'http://example.org/custom#ok': ({ subst }) => [subst],
+  },
+};
+```
+
 If none of those shapes match, Eyeling rejects the module with a descriptive error.
 
 ### 16.4 The handler contract
 
-Builtin handlers are called with a context object like:
+Builtin handlers are called with a context object containing:
 
 - `iri` — the predicate IRI string
 - `goal` — the current triple goal
 - `subst` — the current substitution
-- `facts`, `backRules`, `depth`, `varGen`, `maxResults`
+- `facts` — the active fact store
+- `backRules` — the backward-rule set
+- `depth` — current proof depth
+- `varGen` — the variable generator state
+- `maxResults` — current result cap
 - `api` — the same registration/helper API used by modules
 
-A handler returns **an array of substitutions**:
+A handler should return an **array of substitution objects**:
 
 - `[]` means failure / no solutions
-- `[subst2]` means one successful continuation
-- multiple substitutions mean a generator builtin
+- `[{}]` means success with no new bindings
+- `[{ ...delta }]` means one successful continuation with bindings
+- multiple objects mean a generator builtin
+
+Returning something else is rejected at runtime.
 
 In practice:
 
@@ -2153,13 +2197,24 @@ Custom builtin failures are wrapped so the predicate IRI appears in the thrown e
 
 ### 16.5 The helper API exposed to builtin modules
 
-Builtin modules do not need to import internal engine files directly. Eyeling passes a helper API into module registration, including:
+Builtin modules do not need to import internal engine files directly. Eyeling passes a helper API into module registration, and that helper surface is kept intentionally small.
+
+The current helper function set is:
+
+- `registerBuiltin`, `unregisterBuiltin`, `listBuiltinIris`
+- `internIri`, `internLiteral`, `literalParts`
+- `termToJsString`, `termToJsStringDecoded`, `termToN3`, `iriValue`
+- `unifyTerm`, `applySubstTerm`, `applySubstTriple`, `proveGoals`, `isGroundTerm`
+- `computeConclusionFromFormula`, `skolemIriFromGroundTerm`
+- `parseBooleanLiteralInfo`, `parseNumericLiteralInfo`, `parseXsdDecimalToBigIntScale`, `pow10n`
+- `normalizeLiteralForFastKey`, `literalsEquivalentAsXsdString`, `materializeRdfLists`
+
+The stable namespace bags are:
+
+- `terms`: `Literal`, `Iri`, `Var`, `Blank`, `ListTerm`, `OpenListTerm`, `GraphTerm`, `Triple`, `Rule`
+- `ns`: `RDF_NS`, `XSD_NS`, `CRYPTO_NS`, `MATH_NS`, `TIME_NS`, `LIST_NS`, `LOG_NS`, `STRING_NS`
 
-- registration helpers: `registerBuiltin`, `unregisterBuiltin`, `listBuiltinIris`
-- term constructors via `terms` (`Literal`, `Iri`, `Var`, `Blank`, `ListTerm`, `GraphTerm`, `Triple`, `Rule`, ...)
-- literal/term helpers such as `internLiteral`, `internIri`, `literalParts`, `termToN3`, `termToJsString`
-- reasoning helpers such as `unifyTerm`, `applySubstTerm`, `applySubstTriple`, `proveGoals`
-- namespace constants via `ns`
+The helper object is frozen and regression-tested so helper additions, removals, and renames do not slip in silently.
 
 That API keeps the extension boundary explicit: custom builtins get the operations they need without reaching into Eyeling’s private module graph.
 

package/eyeling.js

@@ -558,8 +558,15 @@ function registerBuiltin(iri, handler) {
   if (typeof handler !== 'function') {
     throw new TypeError(`Custom builtin ${iri} must be registered with a function handler`);
   }
-  __customBuiltinHandlers.set(iri, handler);
-  return handler;
+
+  const wrapped = function builtinResultWrapper(ctx) {
+    const out = handler(ctx);
+    __assertBuiltinHandlerResult(iri, out);
+    return out;
+  };
+
+  __customBuiltinHandlers.set(iri, wrapped);
+  return wrapped;
 }
 
 function unregisterBuiltin(iri) {
@@ -570,8 +577,30 @@ function listBuiltinIris() {
   return Array.from(__customBuiltinHandlers.keys()).sort();
 }
 
+let __builtinApiSingleton = null;
+
+function __freezeBuiltinApi(api) {
+  Object.freeze(api.terms);
+  Object.freeze(api.ns);
+  return Object.freeze(api);
+}
+
+function __assertBuiltinHandlerResult(iri, out) {
+  if (out == null) return;
+  if (!Array.isArray(out)) {
+    throw new TypeError(`Custom builtin ${iri} must return an array of substitution deltas`);
+  }
+  for (const delta of out) {
+    if (!delta || typeof delta !== 'object' || Array.isArray(delta)) {
+      throw new TypeError(`Custom builtin ${iri} must return an array of substitution deltas`);
+    }
+  }
+}
+
 function __buildBuiltinRegistrationApi() {
-  return {
+  if (__builtinApiSingleton) return __builtinApiSingleton;
+
+  const api = {
     registerBuiltin,
     unregisterBuiltin,
     listBuiltinIris,
@@ -599,6 +628,9 @@ function __buildBuiltinRegistrationApi() {
     terms: { Literal, Iri, Var, Blank, ListTerm, OpenListTerm, GraphTerm, Triple, Rule },
     ns: { RDF_NS, XSD_NS, CRYPTO_NS, MATH_NS, TIME_NS, LIST_NS, LOG_NS, STRING_NS },
   };
+
+  __builtinApiSingleton = __freezeBuiltinApi(api);
+  return __builtinApiSingleton;
 }
 
 function registerBuiltinModule(mod, origin = '<builtin-module>') {
@@ -675,9 +707,7 @@ function __evalRegisteredBuiltin(pv, goal, subst, facts, backRules, depth, varGe
   try {
     const out = handler(ctx);
     if (out == null) return [];
-    if (!Array.isArray(out)) {
-      throw new TypeError(`Custom builtin ${pv} must return an array of substitution deltas`);
-    }
+    __assertBuiltinHandlerResult(pv, out);
     return out;
   } catch (err) {
     if (err && typeof err === 'object' && typeof err.message === 'string') {
@@ -4472,6 +4502,7 @@ module.exports = {
   registerBuiltinModule,
   loadBuiltinModule,
   listBuiltinIris,
+  __testBuildBuiltinApi: __buildBuiltinRegistrationApi,
   // shared helpers used by engine/explain
   parseBooleanLiteralInfo,
   parseNumericLiteralInfo,

package/lib/builtins.js

@@ -78,8 +78,15 @@ function registerBuiltin(iri, handler) {
   if (typeof handler !== 'function') {
     throw new TypeError(`Custom builtin ${iri} must be registered with a function handler`);
   }
-  __customBuiltinHandlers.set(iri, handler);
-  return handler;
+
+  const wrapped = function builtinResultWrapper(ctx) {
+    const out = handler(ctx);
+    __assertBuiltinHandlerResult(iri, out);
+    return out;
+  };
+
+  __customBuiltinHandlers.set(iri, wrapped);
+  return wrapped;
 }
 
 function unregisterBuiltin(iri) {
@@ -90,8 +97,30 @@ function listBuiltinIris() {
   return Array.from(__customBuiltinHandlers.keys()).sort();
 }
 
+let __builtinApiSingleton = null;
+
+function __freezeBuiltinApi(api) {
+  Object.freeze(api.terms);
+  Object.freeze(api.ns);
+  return Object.freeze(api);
+}
+
+function __assertBuiltinHandlerResult(iri, out) {
+  if (out == null) return;
+  if (!Array.isArray(out)) {
+    throw new TypeError(`Custom builtin ${iri} must return an array of substitution deltas`);
+  }
+  for (const delta of out) {
+    if (!delta || typeof delta !== 'object' || Array.isArray(delta)) {
+      throw new TypeError(`Custom builtin ${iri} must return an array of substitution deltas`);
+    }
+  }
+}
+
 function __buildBuiltinRegistrationApi() {
-  return {
+  if (__builtinApiSingleton) return __builtinApiSingleton;
+
+  const api = {
     registerBuiltin,
     unregisterBuiltin,
     listBuiltinIris,
@@ -119,6 +148,9 @@ function __buildBuiltinRegistrationApi() {
     terms: { Literal, Iri, Var, Blank, ListTerm, OpenListTerm, GraphTerm, Triple, Rule },
     ns: { RDF_NS, XSD_NS, CRYPTO_NS, MATH_NS, TIME_NS, LIST_NS, LOG_NS, STRING_NS },
   };
+
+  __builtinApiSingleton = __freezeBuiltinApi(api);
+  return __builtinApiSingleton;
 }
 
 function registerBuiltinModule(mod, origin = '<builtin-module>') {
@@ -195,9 +227,7 @@ function __evalRegisteredBuiltin(pv, goal, subst, facts, backRules, depth, varGe
   try {
     const out = handler(ctx);
     if (out == null) return [];
-    if (!Array.isArray(out)) {
-      throw new TypeError(`Custom builtin ${pv} must return an array of substitution deltas`);
-    }
+    __assertBuiltinHandlerResult(pv, out);
     return out;
   } catch (err) {
     if (err && typeof err === 'object' && typeof err.message === 'string') {
@@ -3992,6 +4022,7 @@ module.exports = {
   registerBuiltinModule,
   loadBuiltinModule,
   listBuiltinIris,
+  __testBuildBuiltinApi: __buildBuiltinRegistrationApi,
   // shared helpers used by engine/explain
   parseBooleanLiteralInfo,
   parseNumericLiteralInfo,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.19.1",
+  "version": "1.19.3",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [
@@ -40,12 +40,13 @@
     "build": "node tools/bundle.js",
     "test:packlist": "node test/packlist.test.js",
     "test:api": "node test/api.test.js",
+    "test:builtin-contract": "node test/builtin-contract.test.js",
     "test:n3gen": "node test/n3gen.test.js",
     "test:examples": "node test/examples.test.js",
     "test:manifest": "node test/manifest.test.js",
     "test:playground": "node test/playground.test.js",
     "test:package": "node test/package.test.js",
-    "test:all": "npm run test:api && npm run test:n3gen && npm run test:examples && npm run test:manifest && npm run test:playground",
+    "test:all": "npm run test:api && npm run test:builtin-contract && npm run test:n3gen && npm run test:examples && npm run test:manifest && npm run test:playground",
     "pretest": "npm run build && npm run test:packlist",
     "test": "npm run test:all",
     "posttest": "npm run test:package",

package/test/builtin-contract.test.js

@@ -0,0 +1,155 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const TTY = process.stdout.isTTY;
+const C = TTY
+  ? { g: '\x1b[32m', r: '\x1b[31m', y: '\x1b[33m', dim: '\x1b[2m', n: '\x1b[0m' }
+  : { g: '', r: '', y: '', dim: '', n: '' };
+
+function ok(msg) {
+  console.log(`${C.g}OK ${C.n} ${msg}`);
+}
+function info(msg) {
+  console.log(`${C.y}==${C.n} ${msg}`);
+}
+function fail(msg) {
+  console.error(`${C.r}FAIL${C.n} ${msg}`);
+}
+
+const fixtures = path.join(__dirname, 'fixtures', 'builtins');
+const builtins = require('../lib/builtins');
+require('../lib/engine');
+
+const expectedApiKeys = [
+  'registerBuiltin',
+  'unregisterBuiltin',
+  'listBuiltinIris',
+  'internIri',
+  'internLiteral',
+  'literalParts',
+  'termToJsString',
+  'termToJsStringDecoded',
+  'termToN3',
+  'iriValue',
+  'unifyTerm',
+  'applySubstTerm',
+  'applySubstTriple',
+  'proveGoals',
+  'isGroundTerm',
+  'computeConclusionFromFormula',
+  'skolemIriFromGroundTerm',
+  'parseBooleanLiteralInfo',
+  'parseNumericLiteralInfo',
+  'parseXsdDecimalToBigIntScale',
+  'pow10n',
+  'normalizeLiteralForFastKey',
+  'literalsEquivalentAsXsdString',
+  'materializeRdfLists',
+  'terms',
+  'ns',
+].sort();
+
+const expectedTermsKeys = [
+  'Literal',
+  'Iri',
+  'Var',
+  'Blank',
+  'ListTerm',
+  'OpenListTerm',
+  'GraphTerm',
+  'Triple',
+  'Rule',
+].sort();
+const expectedNsKeys = ['RDF_NS', 'XSD_NS', 'CRYPTO_NS', 'MATH_NS', 'TIME_NS', 'LIST_NS', 'LOG_NS', 'STRING_NS'].sort();
+
+const cases = [
+  {
+    name: 'builtin helper API stays stable and frozen',
+    run() {
+      const api = builtins.__testBuildBuiltinApi();
+      assert.deepEqual(Object.keys(api).sort(), expectedApiKeys);
+      assert.equal(Object.isFrozen(api), true);
+      assert.equal(Object.isFrozen(api.terms), true);
+      assert.equal(Object.isFrozen(api.ns), true);
+      assert.deepEqual(Object.keys(api.terms).sort(), expectedTermsKeys);
+      assert.deepEqual(Object.keys(api.ns).sort(), expectedNsKeys);
+    },
+  },
+  {
+    name: 'registerBuiltinModule accepts supported module export forms',
+    run() {
+      assert.doesNotThrow(() => builtins.registerBuiltinModule(require(path.join(fixtures, 'ok-map.js')), 'ok-map'));
+      assert.doesNotThrow(() =>
+        builtins.registerBuiltinModule(require(path.join(fixtures, 'ok-register.js')), 'ok-register'),
+      );
+      assert.doesNotThrow(() =>
+        builtins.registerBuiltinModule(require(path.join(fixtures, 'ok-builtins.js')), 'ok-builtins'),
+      );
+      assert.doesNotThrow(() =>
+        builtins.registerBuiltinModule(require(path.join(fixtures, 'ok-default-map.js')), 'ok-default-map'),
+      );
+    },
+  },
+  {
+    name: 'registerBuiltinModule rejects unsupported module exports',
+    run() {
+      assert.throws(
+        () => builtins.registerBuiltinModule(require(path.join(fixtures, 'bad-export.js')), 'bad-export'),
+        /must export a function, a \{ register\(\) \} object, or an object mapping predicate IRIs to handlers/,
+      );
+    },
+  },
+  {
+    name: 'registered builtin handlers must return substitution arrays',
+    run() {
+      const wrapped = builtins.registerBuiltin('http://example.org/test#shape-check', () => ({ nope: true }));
+      assert.throws(
+        () =>
+          wrapped({
+            iri: 'http://example.org/test#shape-check',
+            goal: {},
+            subst: {},
+            facts: [],
+            backRules: [],
+            depth: 0,
+            varGen: 0,
+            maxResults: 1,
+            api: builtins.__testBuildBuiltinApi(),
+          }),
+        /must return an array of substitution deltas/,
+      );
+    },
+  },
+];
+
+let passed = 0;
+let failed = 0;
+
+(function main() {
+  const suiteStart = Date.now();
+  info(`Running ${cases.length} builtin contract tests`);
+
+  for (const tc of cases) {
+    const start = Date.now();
+    try {
+      tc.run();
+      ok(`${tc.name} ${C.dim}(${Date.now() - start} ms)${C.n}`);
+      passed++;
+    } catch (e) {
+      fail(`${tc.name} ${C.dim}(${Date.now() - start} ms)${C.n}`);
+      fail(e && e.stack ? e.stack : String(e));
+      failed++;
+    }
+  }
+
+  console.log('');
+  console.log(`${C.y}==${C.n} Total elapsed: ${Date.now() - suiteStart} ms`);
+  if (failed === 0) {
+    ok(`All builtin contract tests passed (${passed}/${cases.length})`);
+    process.exit(0);
+  }
+  fail(`Some builtin contract tests failed (${passed}/${cases.length})`);
+  process.exit(1);
+})();

package/test/fixtures/builtins/bad-export.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = 42;

package/test/fixtures/builtins/bad-return.js

@@ -0,0 +1,5 @@
+'use strict';
+
+module.exports = {
+  'http://example.org/test#bad-return': () => ({ nope: true }),
+};

package/test/fixtures/builtins/ok-builtins.js

@@ -0,0 +1,7 @@
+'use strict';
+
+module.exports = {
+  builtins: {
+    'http://example.org/test#ok-builtins': ({ subst }) => [subst],
+  },
+};

package/test/fixtures/builtins/ok-default-map.js

@@ -0,0 +1,7 @@
+'use strict';
+
+module.exports = {
+  default: {
+    'http://example.org/test#ok-default-map': ({ subst }) => [subst],
+  },
+};

package/test/fixtures/builtins/ok-map.js

@@ -0,0 +1,5 @@
+'use strict';
+
+module.exports = {
+  'http://example.org/test#ok': ({ subst }) => [subst],
+};

package/test/fixtures/builtins/ok-register.js

@@ -0,0 +1,7 @@
+'use strict';
+
+module.exports = {
+  register(api) {
+    api.registerBuiltin('http://example.org/test#ok-register', ({ subst }) => [subst]);
+  },
+};