eyeling 1.19.1 → 1.19.2

package/HANDBOOK.md

@@ -2085,9 +2085,26 @@ const { reason } = require('eyeling');
 const out = reason({ builtinModules: ['./hello-builtin.js'] }, n3Text);
 ```
 
+### 16.2.1 Stability rule for `--builtin`
+
+Eyeling now treats the custom-builtin boundary as a **versioned API contract** rather than an informal convenience layer.
+
+That matters for LLM-generated builtin modules: the model is free to decide **when** a builtin should be used, but it is **not** free to rename helpers, invent new helper names, change handler context fields, or change the expected return shape.
+
+The stable rule is:
+
+- builtin module loading accepts only the declared export forms
+- the helper API exposed by `__buildBuiltinRegistrationApi()` has an **exact key set**
+- helper names and helper arities are treated as public contract
+- builtin handlers receive an **exact** context object shape
+- builtin handlers must return an **array of substitution-delta objects**
+- any add/remove/rename of these contract elements is a **breaking change** and should bump the builtin API version
+
+In code, this contract lives in `lib/builtin-contract.js`, is enforced at runtime by `lib/builtins.js`, and is locked by `test/builtin-contract.test.js`.
+
 ### 16.3 What a builtin module may export
 
-Eyeling accepts three module shapes.
+Eyeling accepts these stable module shapes.
 
 #### A function export
 
@@ -2124,23 +2141,54 @@ 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 an **exactly versioned** context object:
 
 - `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**:
+The exact key set is part of the contract; adding, removing, or renaming a context field is a breaking change.
+
+A handler returns **an array of substitution-delta 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 a non-array, `null` elements, or non-object delta elements is rejected by the runtime contract wrapper.
 
 In practice:
 
@@ -2153,13 +2201,28 @@ 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 now treated as an **exact public contract**.
+
+The current builtin API version is exposed as:
+
+- `getBuiltinApiVersion()`
+
+The stable 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 contract is intentionally strict: if a helper is added, removed, renamed, or its callable shape changes, the builtin contract tests fail until the change is made explicit and the version is bumped.
 
 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

@@ -9,6 +9,130 @@
   const __cache = Object.create(null);
 
   // ---- bundled modules ----
+  __modules["lib/builtin-contract.js"] = function(require, module, exports){
+'use strict';
+
+const CONTRACT = {
+  version: 1,
+  moduleExportForms: [
+    'function',
+    'object.register',
+    'object.builtins',
+    'plain-object-map',
+    'object.default-object-map',
+  ],
+  api: {
+    functions: {
+      getBuiltinApiVersion: { arity: 0, required: true },
+      registerBuiltin: { arity: 2, required: true },
+      unregisterBuiltin: { arity: 1, required: true },
+      listBuiltinIris: { arity: 0, required: true },
+      internIri: { arity: 1, required: true },
+      internLiteral: { arity: 1, required: true },
+      literalParts: { arity: 1, required: true },
+      termToJsString: { arity: 1, required: true },
+      termToJsStringDecoded: { arity: 1, required: true },
+      termToN3: { arity: 2, required: true },
+      iriValue: { arity: 1, required: true },
+      unifyTerm: { arity: 3, required: true },
+      applySubstTerm: { arity: 2, required: true },
+      applySubstTriple: { arity: 2, required: true },
+      proveGoals: { arity: 9, required: true },
+      isGroundTerm: { arity: 1, required: true },
+      computeConclusionFromFormula: { arity: 1, required: true },
+      skolemIriFromGroundTerm: { arity: 1, required: true },
+      parseBooleanLiteralInfo: { arity: 1, required: true },
+      parseNumericLiteralInfo: { arity: 1, required: true },
+      parseXsdDecimalToBigIntScale: { arity: 1, required: true },
+      pow10n: { arity: 1, required: true },
+      normalizeLiteralForFastKey: { arity: 1, required: true },
+      literalsEquivalentAsXsdString: { arity: 2, required: true },
+      materializeRdfLists: { arity: 3, required: true },
+    },
+    namespaces: {
+      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'],
+    },
+  },
+  handler: {
+    ctxKeys: ['iri', 'goal', 'subst', 'facts', 'backRules', 'depth', 'varGen', 'maxResults', 'api'],
+    return: 'array-of-substitution-deltas',
+  },
+};
+
+const EXACT_API_KEYS = new Set([...Object.keys(CONTRACT.api.functions), ...Object.keys(CONTRACT.api.namespaces)]);
+
+function assertExactKeys(obj, expectedKeys, label) {
+  const got = Object.keys(obj).sort();
+  const exp = Array.from(expectedKeys).sort();
+  if (got.length !== exp.length || got.some((k, i) => k !== exp[i])) {
+    throw new Error(`${label} keys changed. expected: ${exp.join(', ')}; got: ${got.join(', ')}`);
+  }
+}
+
+function assertFunctionArity(name, fn, spec) {
+  if (typeof fn !== 'function') throw new TypeError(`Builtin API member ${name} must be a function`);
+  if (Number.isInteger(spec.arity) && fn.length !== spec.arity) {
+    throw new Error(`Builtin API member ${name} arity changed: expected ${spec.arity}, got ${fn.length}`);
+  }
+  if (Number.isInteger(spec.arityMin) && fn.length < spec.arityMin) {
+    throw new Error(`Builtin API member ${name} arity too small: expected >= ${spec.arityMin}, got ${fn.length}`);
+  }
+}
+
+function deepFreezeBuiltinApi(api) {
+  Object.freeze(api.terms);
+  Object.freeze(api.ns);
+  return Object.freeze(api);
+}
+
+function assertBuiltinApiShape(api) {
+  assertExactKeys(api, EXACT_API_KEYS, 'Builtin registration API');
+
+  for (const [name, spec] of Object.entries(CONTRACT.api.functions)) {
+    assertFunctionArity(name, api[name], spec);
+  }
+
+  for (const name of CONTRACT.api.namespaces.terms) {
+    if (!api.terms || typeof api.terms[name] !== 'function') {
+      throw new TypeError(`Builtin API terms.${name} missing or invalid`);
+    }
+  }
+
+  for (const name of CONTRACT.api.namespaces.ns) {
+    if (!api.ns || typeof api.ns[name] !== 'string') {
+      throw new TypeError(`Builtin API ns.${name} missing or invalid`);
+    }
+  }
+
+  return api;
+}
+
+function assertBuiltinCtxShape(ctx) {
+  assertExactKeys(ctx, new Set(CONTRACT.handler.ctxKeys), 'Builtin handler ctx');
+}
+
+function assertBuiltinResultShape(out, iri) {
+  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 === null || typeof delta !== 'object' || Array.isArray(delta)) {
+      throw new TypeError(`Custom builtin ${iri} returned a non-object substitution delta`);
+    }
+  }
+}
+
+module.exports = {
+  CONTRACT,
+  assertBuiltinApiShape,
+  assertBuiltinCtxShape,
+  assertBuiltinResultShape,
+  deepFreezeBuiltinApi,
+};
+
+  };
   __modules["lib/builtin-sudoku.js"] = function(require, module, exports){
 'use strict';
 
@@ -515,6 +639,13 @@ const { termToN3 } = require('./printing');
 const trace = require('./trace');
 const time = require('./time');
 const deref = require('./deref');
+const {
+  CONTRACT: BUILTIN_CONTRACT,
+  assertBuiltinApiShape,
+  assertBuiltinCtxShape,
+  assertBuiltinResultShape,
+  deepFreezeBuiltinApi,
+} = require('./builtin-contract');
 
 let nodeCrypto = null;
 try {
@@ -558,8 +689,21 @@ 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 builtinContractWrapper(ctx) {
+    assertBuiltinCtxShape(ctx);
+    const out = handler(ctx);
+    assertBuiltinResultShape(out, iri);
+    return out;
+  };
+
+  Object.defineProperty(wrapped, '__builtinContractWrapped', {
+    value: true,
+    enumerable: false,
+  });
+
+  __customBuiltinHandlers.set(iri, wrapped);
+  return wrapped;
 }
 
 function unregisterBuiltin(iri) {
@@ -570,8 +714,17 @@ function listBuiltinIris() {
   return Array.from(__customBuiltinHandlers.keys()).sort();
 }
 
+let __builtinApiSingleton = null;
+
+function getBuiltinApiVersion() {
+  return BUILTIN_CONTRACT.version;
+}
+
 function __buildBuiltinRegistrationApi() {
-  return {
+  if (__builtinApiSingleton) return __builtinApiSingleton;
+
+  const api = {
+    getBuiltinApiVersion,
     registerBuiltin,
     unregisterBuiltin,
     listBuiltinIris,
@@ -599,6 +752,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 = deepFreezeBuiltinApi(assertBuiltinApiShape(api));
+  return __builtinApiSingleton;
 }
 
 function registerBuiltinModule(mod, origin = '<builtin-module>') {
@@ -675,9 +831,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`);
-    }
+    assertBuiltinResultShape(out, pv);
     return out;
   } catch (err) {
     if (err && typeof err === 'object' && typeof err.message === 'string') {
@@ -4472,6 +4626,8 @@ module.exports = {
   registerBuiltinModule,
   loadBuiltinModule,
   listBuiltinIris,
+  getBuiltinApiVersion,
+  __testBuildBuiltinApi: __buildBuiltinRegistrationApi,
   // shared helpers used by engine/explain
   parseBooleanLiteralInfo,
   parseNumericLiteralInfo,

package/lib/builtin-contract.js

@@ -0,0 +1,121 @@
+'use strict';
+
+const CONTRACT = {
+  version: 1,
+  moduleExportForms: [
+    'function',
+    'object.register',
+    'object.builtins',
+    'plain-object-map',
+    'object.default-object-map',
+  ],
+  api: {
+    functions: {
+      getBuiltinApiVersion: { arity: 0, required: true },
+      registerBuiltin: { arity: 2, required: true },
+      unregisterBuiltin: { arity: 1, required: true },
+      listBuiltinIris: { arity: 0, required: true },
+      internIri: { arity: 1, required: true },
+      internLiteral: { arity: 1, required: true },
+      literalParts: { arity: 1, required: true },
+      termToJsString: { arity: 1, required: true },
+      termToJsStringDecoded: { arity: 1, required: true },
+      termToN3: { arity: 2, required: true },
+      iriValue: { arity: 1, required: true },
+      unifyTerm: { arity: 3, required: true },
+      applySubstTerm: { arity: 2, required: true },
+      applySubstTriple: { arity: 2, required: true },
+      proveGoals: { arity: 9, required: true },
+      isGroundTerm: { arity: 1, required: true },
+      computeConclusionFromFormula: { arity: 1, required: true },
+      skolemIriFromGroundTerm: { arity: 1, required: true },
+      parseBooleanLiteralInfo: { arity: 1, required: true },
+      parseNumericLiteralInfo: { arity: 1, required: true },
+      parseXsdDecimalToBigIntScale: { arity: 1, required: true },
+      pow10n: { arity: 1, required: true },
+      normalizeLiteralForFastKey: { arity: 1, required: true },
+      literalsEquivalentAsXsdString: { arity: 2, required: true },
+      materializeRdfLists: { arity: 3, required: true },
+    },
+    namespaces: {
+      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'],
+    },
+  },
+  handler: {
+    ctxKeys: ['iri', 'goal', 'subst', 'facts', 'backRules', 'depth', 'varGen', 'maxResults', 'api'],
+    return: 'array-of-substitution-deltas',
+  },
+};
+
+const EXACT_API_KEYS = new Set([...Object.keys(CONTRACT.api.functions), ...Object.keys(CONTRACT.api.namespaces)]);
+
+function assertExactKeys(obj, expectedKeys, label) {
+  const got = Object.keys(obj).sort();
+  const exp = Array.from(expectedKeys).sort();
+  if (got.length !== exp.length || got.some((k, i) => k !== exp[i])) {
+    throw new Error(`${label} keys changed. expected: ${exp.join(', ')}; got: ${got.join(', ')}`);
+  }
+}
+
+function assertFunctionArity(name, fn, spec) {
+  if (typeof fn !== 'function') throw new TypeError(`Builtin API member ${name} must be a function`);
+  if (Number.isInteger(spec.arity) && fn.length !== spec.arity) {
+    throw new Error(`Builtin API member ${name} arity changed: expected ${spec.arity}, got ${fn.length}`);
+  }
+  if (Number.isInteger(spec.arityMin) && fn.length < spec.arityMin) {
+    throw new Error(`Builtin API member ${name} arity too small: expected >= ${spec.arityMin}, got ${fn.length}`);
+  }
+}
+
+function deepFreezeBuiltinApi(api) {
+  Object.freeze(api.terms);
+  Object.freeze(api.ns);
+  return Object.freeze(api);
+}
+
+function assertBuiltinApiShape(api) {
+  assertExactKeys(api, EXACT_API_KEYS, 'Builtin registration API');
+
+  for (const [name, spec] of Object.entries(CONTRACT.api.functions)) {
+    assertFunctionArity(name, api[name], spec);
+  }
+
+  for (const name of CONTRACT.api.namespaces.terms) {
+    if (!api.terms || typeof api.terms[name] !== 'function') {
+      throw new TypeError(`Builtin API terms.${name} missing or invalid`);
+    }
+  }
+
+  for (const name of CONTRACT.api.namespaces.ns) {
+    if (!api.ns || typeof api.ns[name] !== 'string') {
+      throw new TypeError(`Builtin API ns.${name} missing or invalid`);
+    }
+  }
+
+  return api;
+}
+
+function assertBuiltinCtxShape(ctx) {
+  assertExactKeys(ctx, new Set(CONTRACT.handler.ctxKeys), 'Builtin handler ctx');
+}
+
+function assertBuiltinResultShape(out, iri) {
+  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 === null || typeof delta !== 'object' || Array.isArray(delta)) {
+      throw new TypeError(`Custom builtin ${iri} returned a non-object substitution delta`);
+    }
+  }
+}
+
+module.exports = {
+  CONTRACT,
+  assertBuiltinApiShape,
+  assertBuiltinCtxShape,
+  assertBuiltinResultShape,
+  deepFreezeBuiltinApi,
+};

package/lib/builtins.js

@@ -35,6 +35,13 @@ const { termToN3 } = require('./printing');
 const trace = require('./trace');
 const time = require('./time');
 const deref = require('./deref');
+const {
+  CONTRACT: BUILTIN_CONTRACT,
+  assertBuiltinApiShape,
+  assertBuiltinCtxShape,
+  assertBuiltinResultShape,
+  deepFreezeBuiltinApi,
+} = require('./builtin-contract');
 
 let nodeCrypto = null;
 try {
@@ -78,8 +85,21 @@ 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 builtinContractWrapper(ctx) {
+    assertBuiltinCtxShape(ctx);
+    const out = handler(ctx);
+    assertBuiltinResultShape(out, iri);
+    return out;
+  };
+
+  Object.defineProperty(wrapped, '__builtinContractWrapped', {
+    value: true,
+    enumerable: false,
+  });
+
+  __customBuiltinHandlers.set(iri, wrapped);
+  return wrapped;
 }
 
 function unregisterBuiltin(iri) {
@@ -90,8 +110,17 @@ function listBuiltinIris() {
   return Array.from(__customBuiltinHandlers.keys()).sort();
 }
 
+let __builtinApiSingleton = null;
+
+function getBuiltinApiVersion() {
+  return BUILTIN_CONTRACT.version;
+}
+
 function __buildBuiltinRegistrationApi() {
-  return {
+  if (__builtinApiSingleton) return __builtinApiSingleton;
+
+  const api = {
+    getBuiltinApiVersion,
     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 = deepFreezeBuiltinApi(assertBuiltinApiShape(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`);
-    }
+    assertBuiltinResultShape(out, pv);
     return out;
   } catch (err) {
     if (err && typeof err === 'object' && typeof err.message === 'string') {
@@ -3992,6 +4022,8 @@ module.exports = {
   registerBuiltinModule,
   loadBuiltinModule,
   listBuiltinIris,
+  getBuiltinApiVersion,
+  __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.2",
   "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,147 @@
+'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');
+const { CONTRACT } = require('../lib/builtin-contract');
+require('../lib/engine');
+
+const expectedApiKeys = [...Object.keys(CONTRACT.api.functions), ...Object.keys(CONTRACT.api.namespaces)].sort();
+
+const expectedFunctionArities = Object.fromEntries(
+  Object.entries(CONTRACT.api.functions).map(([name, spec]) => [name, spec]),
+);
+
+const cases = [
+  {
+    name: 'builtin API exact helper surface is stable',
+    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);
+      for (const [name, spec] of Object.entries(expectedFunctionArities)) {
+        assert.equal(typeof api[name], 'function', `${name} must be a function`);
+        if (Number.isInteger(spec.arity)) assert.equal(api[name].length, spec.arity, `${name} arity drifted`);
+        if (Number.isInteger(spec.arityMin)) assert.ok(api[name].length >= spec.arityMin, `${name} arity drifted`);
+      }
+      assert.deepEqual(Object.keys(api.terms).sort(), CONTRACT.api.namespaces.terms.slice().sort());
+      assert.deepEqual(Object.keys(api.ns).sort(), CONTRACT.api.namespaces.ns.slice().sort());
+      assert.equal(api.getBuiltinApiVersion(), CONTRACT.version);
+    },
+  },
+  {
+    name: 'registerBuiltinModule accepts all declared 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-delta arrays',
+    run() {
+      builtins.registerBuiltinModule(require(path.join(fixtures, 'bad-return.js')), 'bad-return');
+      assert.throws(() => {
+        const h = builtins.registerBuiltin('http://example.org/test#shape-check', () => ({ nope: true }));
+        h({
+          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/);
+    },
+  },
+  {
+    name: 'registered builtin handlers receive the exact stable ctx shape',
+    run() {
+      const wrapped = builtins.registerBuiltin('http://example.org/test#ctx-shape', ({ subst }) => [subst]);
+      assert.throws(
+        () =>
+          wrapped({
+            iri: 'http://example.org/test#ctx-shape',
+            goal: {},
+            subst: {},
+            facts: [],
+            backRules: [],
+            depth: 0,
+            varGen: 0,
+            maxResults: 1,
+            api: builtins.__testBuildBuiltinApi(),
+            extra: true,
+          }),
+        /Builtin handler ctx keys changed|Builtin handler ctx shape changed/,
+      );
+    },
+  },
+];
+
+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]);
+  },
+};