eyelang 0.1.4 → 0.1.6

package/README.md

@@ -1,7 +1,7 @@
 # Eyelang
 
--[![npm version](https://img.shields.io/npm/v/eyelang.svg)](https://www.npmjs.com/package/eyelang)
--[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20761726-blue.svg)](https://doi.org/10.5281/zenodo.20761726)
+[![npm version](https://img.shields.io/npm/v/eyelang.svg)](https://www.npmjs.com/package/eyelang)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20761726-blue.svg)](https://doi.org/10.5281/zenodo.20761726)
 
 Eyelang is a small logic programming language for rules, goals, answers, and proofs.
 Its source syntax is a deliberately small subset of ordinary Prolog term and Horn-clause syntax.
@@ -34,26 +34,6 @@ console.log(result.stdout);
 - [Guide](docs/guide.md)
 - [Language reference](docs/language-reference.md)
 
-### Eyelang built-ins
-
-The Eyelang engine has its own built-in registry under `src/builtins/`. Built-ins are called as ordinary Eyelang predicates. See the [Eyelang language reference](docs/language-reference.md#9-standard-built-in-predicates) for the portable profile. The bundled implementation currently registers 80 name/arity entries across 78 predicate names:
-
-| Family | Count | Built-ins |
-|---|---:|---|
-| Core and host | 4 | `eq/2`, `neq/2`, `local_time/1`, `difference/3` |
-| Arithmetic, comparison, and generators | 29 | `neg/2`, `abs/2`, `sin/2`, `cos/2`, `tan/2`, `asin/2`, `acos/2`, `sqrt/2`, `floor/2`, `ceiling/2`, `trunc/2`, `rounded/2`, `exp/2`, `log/2`, `add/3`, `sub/3`, `mul/3`, `div/3`, `mod/3`, `min/3`, `max/3`, `pow/3`, `atan2/3`, `lt/2`, `gt/2`, `le/2`, `ge/2`, `between/3`, `smallest_divisor_from/3` |
-| Strings and conversions | 15 | `str_concat/3`, `contains/2`, `matches/2`, `matches/3`, `not_matches/2`, `split/3`, `join/3`, `substring/4`, `replace/4`, `lowercase/2`, `uppercase/2`, `trim/2`, `number_string/2`, `atom_string/2`, `term_string/2` |
-| Lists | 19 | `append/3`, `nth0/3`, `set_nth0/4`, `head/2`, `rest/2`, `last/2`, `take/3`, `drop/3`, `slice/4`, `member/2`, `select/3`, `not_member/2`, `reverse/2`, `length/2`, `sum_list/2`, `min_list/2`, `max_list/2`, `list_to_set/2`, `sort/2` |
-| Aggregation | 5 | `findall/3`, `countall/2`, `sumall/3`, `aggregate_min/5`, `aggregate_max/5` |
-| Control | 3 | `not/1`, `once/1`, `forall/2` |
-| Context and terms | 5 | `holds/2`, `holds/3`, `functor/3`, `arg/3`, `compound_name_arguments/3` |
-| **Total** | **80** |  |
-
-
-## Custom built-ins
-
-Custom built-ins can be supplied by creating a `BuiltinRegistry` and passing it to the solver or `run` API.
-
 ## Tests
 
 ```bash

package/docs/guide.md

@@ -238,9 +238,19 @@ The playground has matching `--stats` and `--proof` checkboxes, so browser runs
 
 ### Builtins
 
-Eyelang builtins are registered by name and arity in small modules under [`src/builtins`](../src/builtins). This keeps the runtime portable to Node.js and the browser while giving each builtin family a clear boundary. Builtins are enabled by normal predicate calls.
+Eyelang builtins are registered by name and arity in small modules under [`src/builtins`](../src/builtins). This keeps the runtime portable to Node.js and the browser while giving each builtin family a clear boundary. Built-ins are called as ordinary Eyelang predicates. See the [Eyelang language reference](language-reference.md#9-standard-built-in-predicates) for the portable profile. The bundled implementation currently registers 80 name/arity entries across 78 predicate names:
+
+| Family | Count | Built-ins |
+|---|---:|---|
+| Core and host | 4 | `eq/2`, `neq/2`, `local_time/1`, `difference/3` |
+| Arithmetic, comparison, and generators | 29 | `neg/2`, `abs/2`, `sin/2`, `cos/2`, `tan/2`, `asin/2`, `acos/2`, `sqrt/2`, `floor/2`, `ceiling/2`, `trunc/2`, `rounded/2`, `exp/2`, `log/2`, `add/3`, `sub/3`, `mul/3`, `div/3`, `mod/3`, `min/3`, `max/3`, `pow/3`, `atan2/3`, `lt/2`, `gt/2`, `le/2`, `ge/2`, `between/3`, `smallest_divisor_from/3` |
+| Strings and conversions | 15 | `str_concat/3`, `contains/2`, `matches/2`, `matches/3`, `not_matches/2`, `split/3`, `join/3`, `substring/4`, `replace/4`, `lowercase/2`, `uppercase/2`, `trim/2`, `number_string/2`, `atom_string/2`, `term_string/2` |
+| Lists | 19 | `append/3`, `nth0/3`, `set_nth0/4`, `head/2`, `rest/2`, `last/2`, `take/3`, `drop/3`, `slice/4`, `member/2`, `select/3`, `not_member/2`, `reverse/2`, `length/2`, `sum_list/2`, `min_list/2`, `max_list/2`, `list_to_set/2`, `sort/2` |
+| Aggregation | 5 | `findall/3`, `countall/2`, `sumall/3`, `aggregate_min/5`, `aggregate_max/5` |
+| Control | 3 | `not/1`, `once/1`, `forall/2` |
+| Context and terms | 5 | `holds/2`, `holds/3`, `functor/3`, `arg/3`, `compound_name_arguments/3` |
+| **Total** | **80** |  |
 
-The builtin families cover unification, arithmetic, comparison, dates, strings, lists, aggregation, context terms, term inspection, and search control. Domain-specific number-theory and matrix helper modules were removed from the default registry because those predicates were examples/accelerators rather than a reusable portable surface. New reusable helpers cover common numeric functions, list slicing and summaries, string normalization/conversion, term inspection/construction, and `forall/2`. 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 [`src/builtins/registry.js`](../src/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.
 
@@ -279,8 +289,6 @@ 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/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
 
@@ -457,8 +465,8 @@ The conformance suite lives in [`test/conformance/`](../test/conformance/) as on
 Common commands:
 
 ```sh
-npm run test:eyelang        # integration check plus eyelang corpus
-npm run test:eyelang:corpus # conformance, regression/API/white-box, examples, and proof examples
+npm run test:eyelang        # alias for npm test
+npm test                    # full conformance, regression/API/white-box, examples, and proof examples
 node test/run-conformance.mjs
 node test/run-regression.mjs
 node test/run-examples.mjs

package/docs/language-reference.md

@@ -39,7 +39,7 @@
   - [9.6 Strings and atom constants](#96-strings-and-atom-constants)
   - [9.7 Lists](#97-lists)
   - [9.8 Aggregation and ordering](#98-aggregation-and-ordering)
-  - [9.9 Context terms](#99-context-terms)
+  - [9.9 Context and term inspection](#99-context-and-term-inspection)
   - [9.10 Search control](#910-search-control)
 - [10. Implementation-specific built-ins](#10-implementation-specific-built-ins)
 - [11. Declarations](#11-declarations)
@@ -475,8 +475,6 @@ 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/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/index.d.ts

@@ -6,6 +6,11 @@ export interface EyelangRunOptions {
   proof?: boolean;
   why?: boolean;
   explain?: boolean;
+  maxDepth?: number;
+  solutionLimit?: number;
+  registry?: BuiltinRegistry;
+  sourceMetadata?: boolean;
+  markRecursive?: boolean;
   [key: string]: unknown;
 }
 
@@ -20,61 +25,194 @@ export interface EyelangSourcePart {
   filename?: string;
 }
 
+export interface EyelangClause {
+  head: EyelangTerm;
+  body: EyelangTerm[];
+  index?: number;
+  filename?: string;
+  clauseNumber?: number;
+}
+
+export interface EyelangPredicateGroup {
+  name: string;
+  arity: number;
+  clauses: EyelangClause[];
+  argIndexes: unknown[];
+  pairIndexes: unknown[];
+  memoized: boolean;
+  recursive: boolean;
+}
+
+export type EyelangTerm = Term | { type: string; name: string; args?: EyelangTerm[]; arity?: number };
+
+export class Term {
+  constructor(type: string, name?: unknown, args?: EyelangTerm[]);
+  type: string;
+  name: string;
+  args: EyelangTerm[];
+  get arity(): number;
+}
+
+export class Env {
+  constructor(bindings?: Iterable<readonly [string, EyelangTerm]> | null);
+  bindings: Map<string, EyelangTerm>;
+  clone(): Env;
+  has(name: string): boolean;
+  get(name: string): EyelangTerm | undefined;
+  bind(name: string, term: EyelangTerm): void;
+}
+
 export class Program {
-  constructor(clauses?: unknown[], options?: EyelangRunOptions);
+  constructor(clauses?: EyelangClause[], options?: EyelangRunOptions);
+  clauses: EyelangClause[];
+  groups: Map<string, EyelangPredicateGroup>;
+  materializedGroups: Set<string>;
+  hasMaterialize: boolean;
   static parse(source: string, options?: EyelangRunOptions): Program;
   static parseSources(sources?: Array<string | EyelangSourcePart>, options?: EyelangRunOptions): Program;
-  materializationGoals(): unknown[];
+  makeGroup(name: string, arity: number): EyelangPredicateGroup;
+  indexClause(clause: EyelangClause): void;
+  findGroup(name: string, arity: number): EyelangPredicateGroup | null;
+  applyDeclarations(options?: EyelangRunOptions): void;
+  markRecursivePredicates(): void;
+  hasMaterializeDeclarations(): boolean;
+  groupIsMaterialized(group: EyelangPredicateGroup): boolean;
+  groupHasRule(group: EyelangPredicateGroup): boolean;
   sourceFactLines(predicateKeys?: Set<string> | null): Set<string>;
+  materializationGoals(): EyelangTerm[];
 }
 
-export function makeProgram(clauses?: unknown[], options?: EyelangRunOptions): Program;
-export function parseClauses(source: string, options?: EyelangRunOptions): unknown[];
-export function parseProgramText(source: string, options?: EyelangRunOptions): unknown[];
+export interface BuiltinDefinition {
+  name: string;
+  arity: number;
+  handler: BuiltinHandler;
+  deterministic: boolean;
+  ready: ((solver: Solver, goal: EyelangTerm, env: Env) => boolean) | null;
+  fallbackWhenNotReady: boolean;
+  shouldUse: ((solver: Solver, goal: EyelangTerm, env: Env) => boolean) | null;
+}
 
-export class Env {
-  constructor(parent?: Env | null);
+export type BuiltinHandler = (context: { solver: Solver; goal: EyelangTerm; env: Env }) => Iterable<Env>;
+
+export class BuiltinRegistry {
+  constructor();
+  defs: Map<string, BuiltinDefinition>;
+  add(name: string, arity: number, handler: BuiltinHandler, options?: Partial<BuiltinDefinition>): this;
+  get(name: string, arity: number): BuiltinDefinition | null;
 }
 
 export class Solver {
   constructor(program: Program, options?: EyelangRunOptions);
+  program: Program;
+  registry: BuiltinRegistry;
+  maxDepth: number;
+  solutionLimit: number;
+  solutionsSeen: number;
+  active: unknown[];
+  memo: Map<string, unknown>;
   stats: EyelangStats;
-  solve(goals: unknown[], env?: Env, depth?: number): Iterable<Env>;
+  cloneForInnerGoal(solutionLimit?: number): Solver;
+  solve(goals: EyelangTerm | EyelangTerm[], env?: Env, depth?: number): Iterable<Env>;
+  activeVariant(goal: EyelangTerm, env: Env): boolean;
 }
 
-export class BuiltinRegistry {
-  constructor();
-}
+export const VAR: 'var';
+export const ATOM: 'atom';
+export const STRING: 'string';
+export const NUMBER: 'number';
+export const COMPOUND: 'compound';
 
+export function variable(name: string): Term;
+export function atom(name: string): Term;
+export function stringTerm(value: string): Term;
+export function numberTerm(value: string | number): Term;
+export function compound(name: string, args?: EyelangTerm[]): Term;
+export function emptyList(): Term;
+export function cons(head: EyelangTerm, tail: EyelangTerm): Term;
+export function deref(term: EyelangTerm, env: Env): EyelangTerm;
+export function isScalar(term: EyelangTerm | null | undefined): boolean;
+export function isEmptyList(term: EyelangTerm | null | undefined): boolean;
+export function isCons(term: EyelangTerm | null | undefined): boolean;
+export function isConjunction(term: EyelangTerm | null | undefined): boolean;
+export function unify(left: EyelangTerm, right: EyelangTerm, env: Env): boolean;
+export function cloneTerm(term: EyelangTerm): Term;
+export function freshTerm(term: EyelangTerm, suffix: string | number): Term;
+export function copyResolved(term: EyelangTerm, env: Env): Term;
+export function termIsGround(term: EyelangTerm, env?: Env): boolean;
+export function termToString(term: EyelangTerm, env?: Env, quoteStrings?: boolean): string;
+export function lexicalValue(term: EyelangTerm, env: Env): string | null;
+export function properListItems(list: EyelangTerm, env: Env): EyelangTerm[] | null;
+export function listFromItems(items: EyelangTerm[], start?: number, end?: number, tail?: EyelangTerm): Term;
+export function flattenConjunction(goal: EyelangTerm): EyelangTerm[];
+export function termSignature(term: EyelangTerm | null | undefined): string | null;
+export function variantTerms(left: EyelangTerm, leftEnv: Env, right: EyelangTerm, rightEnv: Env, pairs?: Map<string, string>, reverse?: Map<string, string>): boolean;
+export function compareTerms(left: EyelangTerm, right: EyelangTerm): number;
+export function isDecimalInteger(text: string | null | undefined): boolean;
+export function compareIntegerText(left: string, right: string): number;
+export function parseFiniteNumber(text: string | null | undefined): number | null;
+export function numberTextFromDouble(value: number): string | null;
+export function compareNumberText(left: string, right: string): number;
+
+export function makeProgram(source: string, options?: EyelangRunOptions): Program;
+export function parseClauses(source: string, options?: EyelangRunOptions): EyelangClause[];
+export function parseProgramText(source: string, options?: EyelangRunOptions): EyelangClause[];
 export function createDefaultRegistry(): BuiltinRegistry;
 export function getDefaultRegistry(): BuiltinRegistry;
-
 export function run(source: string | Program, options?: EyelangRunOptions): EyelangRunResult;
-
-export function whyProof(program: Program, goal: unknown, options?: EyelangRunOptions): { ok: boolean; text: string };
-export function whyNoProof(goal: unknown): string;
-
-export const ATOM: 'atom';
-export const VARIABLE: 'variable';
-export const COMPOUND: 'compound';
-export const NUMBER: 'number';
-export const STRING: 'string';
-export function atom(name: string): unknown;
-export function variable(name: string): unknown;
-export function compound(name: string, args?: unknown[]): unknown;
-export function termToString(term: unknown, env?: Env, quoted?: boolean): string;
+export function whyProof(program: Program, goal: EyelangTerm, options?: EyelangRunOptions): { ok: boolean; text: string };
+export function whyNoProof(goal: EyelangTerm): string;
+export function explainProof(program: Program, goal: EyelangTerm, options?: EyelangRunOptions): { ok: boolean; text: string };
 
 declare const eyelang: {
-  run: typeof run;
+  VAR: typeof VAR;
+  ATOM: typeof ATOM;
+  STRING: typeof STRING;
+  NUMBER: typeof NUMBER;
+  COMPOUND: typeof COMPOUND;
+  Term: typeof Term;
+  Env: typeof Env;
   Program: typeof Program;
+  Solver: typeof Solver;
+  BuiltinRegistry: typeof BuiltinRegistry;
+  variable: typeof variable;
+  atom: typeof atom;
+  stringTerm: typeof stringTerm;
+  numberTerm: typeof numberTerm;
+  compound: typeof compound;
+  emptyList: typeof emptyList;
+  cons: typeof cons;
+  deref: typeof deref;
+  isScalar: typeof isScalar;
+  isEmptyList: typeof isEmptyList;
+  isCons: typeof isCons;
+  isConjunction: typeof isConjunction;
+  unify: typeof unify;
+  cloneTerm: typeof cloneTerm;
+  freshTerm: typeof freshTerm;
+  copyResolved: typeof copyResolved;
+  termIsGround: typeof termIsGround;
+  termToString: typeof termToString;
+  lexicalValue: typeof lexicalValue;
+  properListItems: typeof properListItems;
+  listFromItems: typeof listFromItems;
+  flattenConjunction: typeof flattenConjunction;
+  termSignature: typeof termSignature;
+  variantTerms: typeof variantTerms;
+  compareTerms: typeof compareTerms;
+  isDecimalInteger: typeof isDecimalInteger;
+  compareIntegerText: typeof compareIntegerText;
+  parseFiniteNumber: typeof parseFiniteNumber;
+  numberTextFromDouble: typeof numberTextFromDouble;
+  compareNumberText: typeof compareNumberText;
   makeProgram: typeof makeProgram;
   parseClauses: typeof parseClauses;
   parseProgramText: typeof parseProgramText;
-  Solver: typeof Solver;
-  Env: typeof Env;
-  BuiltinRegistry: typeof BuiltinRegistry;
   createDefaultRegistry: typeof createDefaultRegistry;
   getDefaultRegistry: typeof getDefaultRegistry;
+  run: typeof run;
+  whyProof: typeof whyProof;
+  whyNoProof: typeof whyNoProof;
+  explainProof: typeof explainProof;
 };
 
 export default eyelang;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyelang",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "A small Prolog-syntax-subset logic programming language for rules, goals, answers, and proofs.",
   "type": "module",
   "main": "./index.js",

package/test/run-regression.mjs

@@ -8,6 +8,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import * as publicApi from '../src/index.js';
 import {
   run,
   Program,
@@ -50,6 +51,7 @@ export function runRegression(reporter = new TestReporter()) {
 
   try {
     runSection(reporter, 'Regression', regressionCases());
+    runSection(reporter, 'Documentation sync', documentationSyncCases());
     runSection(reporter, 'API', apiCases());
     runSection(reporter, 'White-box', whiteBoxCases());
   } finally {
@@ -188,26 +190,6 @@ why(
         assertEqual(result.stderr, '', 'stderr');
       },
     },
-    {
-      name: 'README covers every mirrored example',
-      run: () => {
-        const examples = listExampleNames();
-        const readmeExamples = readmeCatalogExampleNames();
-        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: () => {
@@ -274,8 +256,44 @@ why(
   ];
 }
 
+
+function documentationSyncCases() {
+  return [
+    {
+      name: 'language reference builtins match runtime registry',
+      run: () => assertArrayEqual(languageReferenceBuiltinNames(), registeredBuiltinNames(), 'builtins'),
+    },
+    {
+      name: 'guide builtin catalog matches runtime registry',
+      run: () => {
+        assertArrayEqual(guideBuiltinNames(), registeredBuiltinNames(), 'builtins');
+        const summary = guideBuiltinSummary();
+        const actual = registeredBuiltinSummary();
+        assertEqual(summary.entries, actual.entries, 'builtin entry count');
+        assertEqual(summary.names, actual.names, 'builtin predicate name count');
+      },
+    },
+    {
+      name: 'guide example catalog matches examples directory',
+      run: () => assertArrayEqual(guideCatalogExampleNames(), listExampleNames(), 'example catalog'),
+    },
+    {
+      name: 'documentation local links and anchors resolve',
+      run: () => assertArrayEqual(findBrokenDocLinks(), [], 'broken documentation links'),
+    },
+    {
+      name: 'documented npm scripts exist in package.json',
+      run: () => assertArrayEqual(missingDocumentedPackageScripts(), [], 'missing documented npm scripts'),
+    },
+  ];
+}
+
 function apiCases() {
   return [
+    {
+      name: 'public type declarations match runtime exports',
+      run: () => assertArrayEqual(declaredValueExportNames(), runtimeExportNames(), 'public value exports'),
+    },
     {
       name: 'run materialization through public API without proof by default',
       run: () => {
@@ -475,6 +493,7 @@ function runSection(reporter, name, cases) {
 }
 
 function sectionLabel(name) {
+  if (name === 'Documentation sync') return 'documentation sync';
   if (name === 'API') return 'API';
   if (name === 'White-box') return 'white-box';
   return name.toLowerCase();
@@ -519,9 +538,9 @@ function listExampleNames() {
     .sort();
 }
 
-function readmeCatalogExampleNames() {
-  const readme = fs.readFileSync(path.join(packageRoot, 'docs', 'guide.md'), 'utf8');
-  const section = between(readme, '## Example catalog', '## Golden outputs, tests, and conformance');
+function guideCatalogExampleNames() {
+  const guide = fs.readFileSync(path.join(packageRoot, 'docs', 'guide.md'), 'utf8');
+  const section = between(guide, '## Example catalog', '## Golden outputs, tests, and conformance');
   return [...section.matchAll(/examples\/([A-Za-z0-9_-]+)\.pl/g)]
     .map((match) => match[1])
     .filter((name, index, names) => names.indexOf(name) === index)
@@ -532,56 +551,137 @@ 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 registeredBuiltinSummary() {
+  const names = registeredBuiltinNames();
+  return {
+    entries: names.length,
+    names: new Set(names.map((name) => name.split('/')[0])).size,
+  };
 }
 
-function readmeBuiltinSummary() {
-  const readme = fs.readFileSync(path.join(packageRoot, 'README.md'), 'utf8');
-  const section = between(readme, '### Eyelang built-ins', '## Custom built-ins');
+function guideBuiltinNames() {
+  const guide = fs.readFileSync(path.join(packageRoot, 'docs', 'guide.md'), 'utf8');
+  return documentedBuiltinNames(between(guide, '### Builtins', '## Aggregation helpers'));
+}
+
+function guideBuiltinSummary() {
+  const guide = fs.readFileSync(path.join(packageRoot, 'docs', 'guide.md'), 'utf8');
+  const section = between(guide, '### Builtins', '## Aggregation helpers');
   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');
+  if (match == null) throw new Error('guide 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);
-  if (match == null) throw new Error('playground EXAMPLES array not found');
-  return [...match[1].matchAll(/"([^"]+)"/g)]
+function languageReferenceBuiltinNames() {
+  const reference = fs.readFileSync(path.join(packageRoot, 'docs', 'language-reference.md'), 'utf8');
+  return documentedBuiltinNames(between(reference, '## 9. Standard built-in predicates', '## 10. Implementation-specific built-ins'));
+}
+
+function documentedBuiltinNames(section) {
+  const names = [];
+  for (const line of section.split('\n')) {
+    if (!line.trim().startsWith('|') || !line.includes('`')) continue;
+    for (const match of line.matchAll(/`([A-Za-z_][A-Za-z0-9_]*)\(([^`)]*)\)`/g)) {
+      const arity = match[2].trim() === '' ? 0 : match[2].split(',').length;
+      names.push(`${match[1]}/${arity}`);
+    }
+    for (const match of line.matchAll(/`([A-Za-z_][A-Za-z0-9_]*)\/(\d+)`/g)) {
+      names.push(`${match[1]}/${match[2]}`);
+    }
+  }
+  return [...new Set(names)].sort();
+}
+
+function runtimeExportNames() {
+  return Object.keys(publicApi).sort();
+}
+
+function declaredValueExportNames() {
+  const dts = fs.readFileSync(path.join(packageRoot, 'index.d.ts'), 'utf8');
+  return [...dts.matchAll(/^export\s+(?:declare\s+)?(?:class|function|const)\s+([A-Za-z_][A-Za-z0-9_]*)/gm)]
     .map((match) => match[1])
+    .filter((name, index, names) => names.indexOf(name) === index)
     .sort();
 }
 
-function playgroundImportGraph() {
-  const entry = path.join(root, 'playground-worker.mjs');
-  const seen = new Set();
-  const stack = [entry];
-  while (stack.length > 0) {
-    const file = stack.pop();
-    if (seen.has(file)) continue;
-    seen.add(file);
+function missingDocumentedPackageScripts() {
+  const docs = documentationFiles();
+  const missing = [];
+  for (const file of docs) {
     const text = fs.readFileSync(file, 'utf8');
-    for (const spec of moduleSpecifiers(text)) {
-      if (spec.startsWith('node:')) throw new Error(`${path.relative(testRoot, file)} imports ${spec}`);
-      if (!spec.startsWith('.')) continue;
-      const next = path.resolve(path.dirname(file), spec);
-      if (next.startsWith(root) && fs.existsSync(next)) stack.push(next);
+    for (const line of text.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith('npm ') && !line.includes('`npm ')) continue;
+      for (const match of line.matchAll(/\bnpm\s+(?:run\s+)?([A-Za-z0-9:_-]+)/g)) {
+        const command = match[1];
+        if (command === 'install') continue;
+        const script = command === 'test' ? 'test' : command;
+        if (!pkg.scripts?.[script]) missing.push(`${path.relative(packageRoot, file)}: npm ${command === 'test' ? 'test' : `run ${script}`}`);
+      }
     }
   }
-  return [...seen].sort();
+  return [...new Set(missing)].sort();
 }
 
-function moduleSpecifiers(text) {
-  const specs = [];
-  for (const match of text.matchAll(/(?:import|export)\s+(?:[^'"]*?\s+from\s+)?['"]([^'"]+)['"]/g)) specs.push(match[1]);
-  for (const match of text.matchAll(/import\(\s*['"]([^'"]+)['"]\s*\)/g)) specs.push(match[1]);
-  return specs;
+function findBrokenDocLinks() {
+  const broken = [];
+  const anchorsByFile = new Map();
+  for (const file of documentationFiles()) {
+    const text = fs.readFileSync(file, 'utf8');
+    for (const target of markdownLinkTargets(text)) {
+      if (/^(?:https?:|mailto:)/i.test(target)) continue;
+      const [targetPathRaw, fragmentRaw] = target.split('#');
+      const targetPath = targetPathRaw === '' ? file : path.resolve(path.dirname(file), decodeURI(targetPathRaw));
+      const display = `${path.relative(packageRoot, file)} -> ${target}`;
+      if (!fs.existsSync(targetPath)) {
+        broken.push(`${display} (missing target)`);
+        continue;
+      }
+      if (fragmentRaw != null && fragmentRaw !== '') {
+        const anchors = anchorsByFile.get(targetPath) ?? markdownAnchors(targetPath);
+        anchorsByFile.set(targetPath, anchors);
+        if (!anchors.has(fragmentRaw)) broken.push(`${display} (missing heading #${fragmentRaw})`);
+      }
+    }
+  }
+  return broken.sort();
+}
+
+function documentationFiles() {
+  return [
+    path.join(packageRoot, 'README.md'),
+    path.join(packageRoot, 'docs', 'guide.md'),
+    path.join(packageRoot, 'docs', 'language-reference.md'),
+  ];
+}
+
+function markdownLinkTargets(text) {
+  return [...text.matchAll(/!?\[[^\]\n]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g)].map((match) => match[1]);
+}
+
+function markdownAnchors(file) {
+  if (!file.endsWith('.md')) return new Set();
+  const text = fs.readFileSync(file, 'utf8');
+  const anchors = new Set();
+  const counts = new Map();
+  for (const match of text.matchAll(/^#{1,6}\s+(.+)$/gm)) {
+    const base = githubSlug(match[1]);
+    const count = counts.get(base) ?? 0;
+    counts.set(base, count + 1);
+    anchors.add(count === 0 ? base : `${base}-${count}`);
+  }
+  return anchors;
+}
+
+function githubSlug(heading) {
+  return heading
+    .replace(/`([^`]*)`/g, '$1')
+    .replace(/<[^>]+>/g, '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{Letter}\p{Number}\s-]/gu, '')
+    .trim()
+    .replace(/\s+/g, '-');
 }
 
 function between(text, startMarker, endMarker) {
@@ -614,6 +714,16 @@ function assertNotIncludes(actual, expected, label) {
   if (String(actual).includes(expected)) throw new Error(`${label} unexpectedly included ${format(expected)}\nactual: ${format(actual)}`);
 }
 
+function assertArrayEqual(actual, expected, label) {
+  const actualText = actual.join('\n');
+  const expectedText = expected.join('\n');
+  if (actualText !== expectedText) {
+    const onlyActual = actual.filter((item) => !expected.includes(item));
+    const onlyExpected = expected.filter((item) => !actual.includes(item));
+    throw new Error(`${label} mismatch\nonly actual: ${format(onlyActual)}\nonly expected: ${format(onlyExpected)}`);
+  }
+}
+
 function format(value) {
   return typeof value === 'string' ? JSON.stringify(value) : String(value);
 }