eyeling 1.19.2 → 1.19.3

package/HANDBOOK.md

@@ -2087,20 +2087,18 @@ 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.
+Eyeling keeps `--builtin` simple.
 
-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.
+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.
 
-The stable rule is:
+In practice, this means:
 
-- 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
+- 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`
 
-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`.
+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
 
@@ -2167,7 +2165,7 @@ If none of those shapes match, Eyeling rejects the module with a descriptive err
 
 ### 16.4 The handler contract
 
-Builtin handlers are called with an **exactly versioned** context object:
+Builtin handlers are called with a context object containing:
 
 - `iri` — the predicate IRI string
 - `goal` — the current triple goal
@@ -2179,16 +2177,14 @@ Builtin handlers are called with an **exactly versioned** context object:
 - `maxResults` — current result cap
 - `api` — the same registration/helper API used by modules
 
-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**:
+A handler should return an **array of substitution objects**:
 
 - `[]` means failure / no solutions
 - `[{}]` 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.
+Returning something else is rejected at runtime.
 
 In practice:
 
@@ -2201,13 +2197,9 @@ 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, and that helper surface is now treated as an **exact public contract**.
-
-The current builtin API version is exposed as:
-
-- `getBuiltinApiVersion()`
+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 stable helper function set is:
+The current helper function set is:
 
 - `registerBuiltin`, `unregisterBuiltin`, `listBuiltinIris`
 - `internIri`, `internLiteral`, `literalParts`
@@ -2222,7 +2214,7 @@ 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`
 
-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.
+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

@@ -9,130 +9,6 @@
   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';
 
@@ -639,13 +515,6 @@ 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 {
@@ -690,18 +559,12 @@ function registerBuiltin(iri, handler) {
     throw new TypeError(`Custom builtin ${iri} must be registered with a function handler`);
   }
 
-  const wrapped = function builtinContractWrapper(ctx) {
-    assertBuiltinCtxShape(ctx);
+  const wrapped = function builtinResultWrapper(ctx) {
     const out = handler(ctx);
-    assertBuiltinResultShape(out, iri);
+    __assertBuiltinHandlerResult(iri, out);
     return out;
   };
 
-  Object.defineProperty(wrapped, '__builtinContractWrapped', {
-    value: true,
-    enumerable: false,
-  });
-
   __customBuiltinHandlers.set(iri, wrapped);
   return wrapped;
 }
@@ -716,15 +579,28 @@ function listBuiltinIris() {
 
 let __builtinApiSingleton = null;
 
-function getBuiltinApiVersion() {
-  return BUILTIN_CONTRACT.version;
+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() {
   if (__builtinApiSingleton) return __builtinApiSingleton;
 
   const api = {
-    getBuiltinApiVersion,
     registerBuiltin,
     unregisterBuiltin,
     listBuiltinIris,
@@ -753,7 +629,7 @@ function __buildBuiltinRegistrationApi() {
     ns: { RDF_NS, XSD_NS, CRYPTO_NS, MATH_NS, TIME_NS, LIST_NS, LOG_NS, STRING_NS },
   };
 
-  __builtinApiSingleton = deepFreezeBuiltinApi(assertBuiltinApiShape(api));
+  __builtinApiSingleton = __freezeBuiltinApi(api);
   return __builtinApiSingleton;
 }
 
@@ -831,7 +707,7 @@ function __evalRegisteredBuiltin(pv, goal, subst, facts, backRules, depth, varGe
   try {
     const out = handler(ctx);
     if (out == null) return [];
-    assertBuiltinResultShape(out, pv);
+    __assertBuiltinHandlerResult(pv, out);
     return out;
   } catch (err) {
     if (err && typeof err === 'object' && typeof err.message === 'string') {
@@ -4626,7 +4502,6 @@ module.exports = {
   registerBuiltinModule,
   loadBuiltinModule,
   listBuiltinIris,
-  getBuiltinApiVersion,
   __testBuildBuiltinApi: __buildBuiltinRegistrationApi,
   // shared helpers used by engine/explain
   parseBooleanLiteralInfo,

package/lib/builtins.js

@@ -35,13 +35,6 @@ 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 {
@@ -86,18 +79,12 @@ function registerBuiltin(iri, handler) {
     throw new TypeError(`Custom builtin ${iri} must be registered with a function handler`);
   }
 
-  const wrapped = function builtinContractWrapper(ctx) {
-    assertBuiltinCtxShape(ctx);
+  const wrapped = function builtinResultWrapper(ctx) {
     const out = handler(ctx);
-    assertBuiltinResultShape(out, iri);
+    __assertBuiltinHandlerResult(iri, out);
     return out;
   };
 
-  Object.defineProperty(wrapped, '__builtinContractWrapped', {
-    value: true,
-    enumerable: false,
-  });
-
   __customBuiltinHandlers.set(iri, wrapped);
   return wrapped;
 }
@@ -112,15 +99,28 @@ function listBuiltinIris() {
 
 let __builtinApiSingleton = null;
 
-function getBuiltinApiVersion() {
-  return BUILTIN_CONTRACT.version;
+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() {
   if (__builtinApiSingleton) return __builtinApiSingleton;
 
   const api = {
-    getBuiltinApiVersion,
     registerBuiltin,
     unregisterBuiltin,
     listBuiltinIris,
@@ -149,7 +149,7 @@ function __buildBuiltinRegistrationApi() {
     ns: { RDF_NS, XSD_NS, CRYPTO_NS, MATH_NS, TIME_NS, LIST_NS, LOG_NS, STRING_NS },
   };
 
-  __builtinApiSingleton = deepFreezeBuiltinApi(assertBuiltinApiShape(api));
+  __builtinApiSingleton = __freezeBuiltinApi(api);
   return __builtinApiSingleton;
 }
 
@@ -227,7 +227,7 @@ function __evalRegisteredBuiltin(pv, goal, subst, facts, backRules, depth, varGe
   try {
     const out = handler(ctx);
     if (out == null) return [];
-    assertBuiltinResultShape(out, pv);
+    __assertBuiltinHandlerResult(pv, out);
     return out;
   } catch (err) {
     if (err && typeof err === 'object' && typeof err.message === 'string') {
@@ -4022,7 +4022,6 @@ module.exports = {
   registerBuiltinModule,
   loadBuiltinModule,
   listBuiltinIris,
-  getBuiltinApiVersion,
   __testBuildBuiltinApi: __buildBuiltinRegistrationApi,
   // shared helpers used by engine/explain
   parseBooleanLiteralInfo,

package/package.json

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

package/test/builtin-contract.test.js

@@ -20,36 +20,65 @@ function fail(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 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 expectedFunctionArities = Object.fromEntries(
-  Object.entries(CONTRACT.api.functions).map(([name, spec]) => [name, spec]),
-);
+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 API exact helper surface is stable',
+    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);
-      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);
+      assert.deepEqual(Object.keys(api.terms).sort(), expectedTermsKeys);
+      assert.deepEqual(Object.keys(api.ns).sort(), expectedNsKeys);
     },
   },
   {
-    name: 'registerBuiltinModule accepts all declared module export forms',
+    name: 'registerBuiltinModule accepts supported module export forms',
     run() {
       assert.doesNotThrow(() => builtins.registerBuiltinModule(require(path.join(fixtures, 'ok-map.js')), 'ok-map'));
       assert.doesNotThrow(() =>
@@ -73,33 +102,13 @@ const cases = [
     },
   },
   {
-    name: 'registered builtin handlers must return substitution-delta arrays',
+    name: 'registered builtin handlers must return substitution 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]);
+      const wrapped = builtins.registerBuiltin('http://example.org/test#shape-check', () => ({ nope: true }));
       assert.throws(
         () =>
           wrapped({
-            iri: 'http://example.org/test#ctx-shape',
+            iri: 'http://example.org/test#shape-check',
             goal: {},
             subst: {},
             facts: [],
@@ -108,9 +117,8 @@ const cases = [
             varGen: 0,
             maxResults: 1,
             api: builtins.__testBuildBuiltinApi(),
-            extra: true,
           }),
-        /Builtin handler ctx keys changed|Builtin handler ctx shape changed/,
+        /must return an array of substitution deltas/,
       );
     },
   },

package/lib/builtin-contract.js

@@ -1,121 +0,0 @@
-'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,
-};