eyeprolog 1.3.78 → 1.3.79

package/README.md

@@ -12,28 +12,22 @@ EyeProlog turns portable ISO Prolog programs into answers and inspectable proofs
   <strong>Click the cover to read <em>The Art of EyeProlog</em>.</strong>
 </p>
 
-**[Why EyeProlog?](https://eyereasoner.github.io/eyeprolog/why-eyeprolog)** — Discover its purpose and design.
-
-**[Playground](https://eyereasoner.github.io/eyeprolog/playground)** — Run EyeProlog in your browser.
-
-The book is the reference for the language, command line, JavaScript API,
-examples, proofs, conformance, and implementation.
+The single implementation reference is [*The Art of EyeProlog*](the-art-of-eyeprolog.md).
+It documents the language, built-ins, libraries, command line, JavaScript API,
+examples, proofs, conformance profile, and implementation.
 
 ## Quick start
 
-EyeProlog requires Node.js 18 or newer. Check the active runtime before
-installing:
+EyeProlog requires Node.js 18 or newer:
 
 ```sh
 node --version
 ```
 
-If it reports an older release, upgrade through a Node version manager or the
-[official Node.js download](https://nodejs.org/en/download) and check again.
-Distribution packages can provide an older Node.js even on a current operating
-system.
+If necessary, upgrade through a Node version manager or the
+[official Node.js download](https://nodejs.org/en/download).
 
-Run EyeProlog without a global installation:
+Run EyeProlog without installing it globally:
 
 ```sh
 npx --yes eyeprolog
@@ -45,8 +39,7 @@ npx --yes eyeprolog
 ?- halt.
 ```
 
-For a persistent `eyeprolog` command without administrator access, install it
-under a user-owned prefix and put that prefix's `bin` directory on `PATH`:
+For a persistent command, use a user-owned npm prefix:
 
 ```sh
 npm install --global --prefix "$HOME/.local" eyeprolog
@@ -54,335 +47,26 @@ export PATH="$HOME/.local/bin:$PATH"
 eyeprolog
 ```
 
-Add the `PATH` export to your shell startup file to keep it across sessions.
-Do not use `sudo npm install`; npm's
-[EACCES guidance](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally/)
-also recommends a Node version manager or a user-owned npm prefix.
+Add the `PATH` export to your shell startup file. Do not use `sudo npm install`;
+npm's [EACCES guidance](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally/)
+also recommends a Node version manager or a user-owned prefix.
 
-For a non-interactive run:
+Run a program non-interactively:
 
 ```sh
 printf 'human(socrates).\nmortal(X) :- human(X).\n' |
   npx --yes eyeprolog --proof --goal 'mortal(socrates)' -
 ```
 
-Programs may declare their default queries with `%% goal:` comments.
-Double-quoted text follows the ISO `double_quotes` flag and defaults to a
-proper list of one-character atoms (`chars`), matching Trealla and Scryer.
-
-Portable unit tests can be embedded as quads—a query followed by its expected
-top-level answer—and run with `eyeprolog --quads program.pl`:
-
-```prolog
-member_test ?- member(X, [prolog, logic]).
-   X = prolog
-;  X = logic.
-```
-
-A label is simply the first argument of the ordinary `(?-)/2` term, so it may
-use any normal Prolog term syntax; EyeProlog only requires it to be ground when
-the quad is checked. A non-ground label is a quad failure, not a source syntax
-error, and later quads still run. When a query has multiple indented answer
-descriptions, each description is checked and counted independently, so one
-failed expectation does not prevent the later ones from running. Following the
-Trealla quad convention, `sto` declares that the query is subject to occurs-check.
-EyeProlog now uses an occurs-check event observed during the query's ordinary
-execution as positive STO evidence, and rejects `sto` when a finite execution
-completes without such an event (for example `?- true. sto.`). If execution is
-cut short by a search/resource boundary, the STO claim remains conservatively
-unverified rather than being guessed.
-For nontermination expectations, `loops` is kept distinct from resource
-exhaustion: structural loop evidence may satisfy `loops`, while a bounded
-search that cannot establish the requested answer sequence is reported as
-`UNDECIDED`. In CLI quad mode, failures use exit status `1`; if there are no
-failures but at least one undecided quad, the exit status is `2`.
-
-## Tabling and well-founded negation
-
-In normal mode, EyeProlog automatically tables eligible positive recursive
-predicates. For large finite, function-free Datalog dependency cones it may use
-one shared relation-wide table, so an open query such as `tc(X, Y)` computes a
-finite closure once and bound recursive calls can reuse indexed answers. The
-choice of when to use relation-wide tabling is an implementation optimization,
-not a language-level threshold or directive.
-
-Recursive nonterminals reached through `phrase/2-3` use a dedicated table
-scope keyed by the complete invocation rather than the caller's general memo.
-When a new input is seen, recursive DCGs that static analysis proves consume a
-list tail on every recursive step run directly without automatic tabling; this
-avoids building and retaining a family of suffix tables that cannot help the
-next distinct input. If the same `phrase/2-3` invocation repeats, normal tabling
-is enabled again and its small completed table can be reused. The retained
-phrase table is also bounded, with active fixed points never evicted. This
-keeps both long-running filters such as `\+ phrase((..., Pattern), Sequence)`
-and repeated same-input probes bounded without turning memory safety into a
-per-call cache-eviction cost.
-
-Finite-tree unification also accepts an internal proven-nonoccurrence hint: when
-the solver can prove that a variable cannot occur in the value it is about to
-receive, that binding skips an otherwise redundant occurs traversal. The main
-source-level case is conservative first use in a freshly renamed clause, inspired
-by the local-variable optimization used by WAM-family systems; native construction
-paths such as relational `length/2` reuse the same unifier mechanism. Repeated
-variables, variables seen earlier in the clause, and ordinary public unification
-remain fully occurs-checked. This is a proof local to one binding, not a WAM-style
-local/global variable stack. `phrase/2` likewise supplies its fixed `[]`
-remainder directly to the grammar; `phrase/3` retains its delayed final output
-unification for steadfastness.
-
-### Delayed disequality with `dif/2`
-
-The normal EyeProlog runtime provides `dif/2` as a conforming extension;
-`--iso-strict` remains limited to ISO/IEC 13211-1 and does not expose it.
-Unlike `\=/2`, which only tests whether two terms are non-unifiable *now*,
-`dif/2` can succeed with a residual disequality constraint and reject a later
-binding that would make the terms identical. For example,
-`dif(X, Y), X = Y` fails, while `dif(X-Y, 1-2), X = Y, Y = 1` succeeds once
-the structural constraint becomes provably satisfied.
-
-The implementation uses backtracking-safe annotated variables in `Env`. A
-pending constraint is indexed by every currently unbound variable it mentions;
-variable aliasing and later bindings reindex the annotation, entailed constraints
-are removed, and violated constraints make unification fail. The interactive
-top level includes pending `dif/2` goals in residual answers. See
-[`examples/dif-constraints.pl`](examples/dif-constraints.pl).
-
-### Attributed variables and CLP(Z)
-
-`library(atts)` exposes Scryer-style attributed-variable operations on the same
-persistent `Env` machinery used by `dif/2`: `put_atts/2`, `get_atts/2`,
-`put_attr/3`, `get_attr/3`, `del_attr/2`, `term_attributed_variables/2`, and
-`call_residue_vars/2`. The latter reports variables whose residual attributes or
-constraints were created or modified by a goal, including native `dif/2` residues.
-`:- attribute ...` declarations are accepted, `verify_attributes/3` runs before
-an attributed binding is committed, and the hook's returned goals run after
-that binding. Attribute state follows variable representatives and ordinary
-Prolog backtracking, and the REPL projects module `attribute_goals//1` hooks as
-residual goals. See [`examples/attributed-variables.pl`](examples/attributed-variables.pl).
-
-`library(clpz)` is the MIT-licensed Scryer Prolog implementation of CLP(Z),
-bundled as `src/lib/clpz.pl`. It provides relational integer arithmetic,
-finite-domain constraints, reification, labeling, global constraints such as
-`all_distinct/1`, `global_cardinality/2,3`, `cumulative/1,2`, `circuit/1`,
-`disjoint2/1`, and `automaton/3,8`, plus domain reflection predicates. The
-bundled source is synchronized with Scryer commit
-`e3df91e25f8a09ee942c04e8baef553bba5c6110` (Git blob
-`806445c11e14c8b2515f3de7f309e0ac04d9ad04`).
-
-EyeProlog's runtime supplies the generic facilities used by that Prolog source:
-attributed variables, user `term_expansion/2` and `goal_expansion/2`, DCG
-expansion through `expand_term/2`, module-aware meta-calls, a backtrackable
-blackboard, and the support modules `assoc`, `pairs`, `between`, `dcgs`, `terms`,
-`error`, `si`, `freeze`, `arithmetic`, `debug`, and `format`.
-
-Recursion through negation is explicit. EyeProlog provides `tnot/1` for
-well-founded negation over finite, range-restricted, function-free Datalog
-components. Ordinary `\+/1` remains negation-as-failure and is not silently
-reinterpreted as WFS.
-
-```prolog
-move(1, 2).
-move(2, 1).
-win(X) :- move(X, Y), tnot(win(Y)).
-
-%% goal: win(X)
-```
-
-A cycle through `tnot/1` can leave atoms *undefined* rather than true or false.
-EyeProlog exposes those as conditional successes so they can participate in
-collectors such as `findall/3`; it does not currently expose a residual-program
-API. Direct `tnot/1` calls must be ground. Variables used in an eligible WFS
-rule are range-restricted by positive body literals before they are negated.
-
-The normal-mode statistics interface includes `wfs_fixpoint_rounds` and
-`wfs_undefined_answers`:
-
-```prolog
-statistics(wfs_fixpoint_rounds, Rounds).
-statistics(wfs_undefined_answers, UndefinedObservations).
-```
-
-Both automatic tabling and `tnot/1` are EyeProlog extensions. Strict ISO mode
-disables automatic tabling and does not provide `tnot/1`.
-
-## Cleanup-aware control
-
-Normal mode provides `call_cleanup/2` and `setup_call_cleanup/3` for resource
-lifetimes that follow Prolog search. Cleanup runs exactly once when the protected
-goal completes deterministically, is exhausted, is cut or otherwise pruned, the
-top level stops answer enumeration, or an exception unwinds the search.
-`setup_call_cleanup/3` runs Setup once and installs Cleanup only after Setup
-succeeds. On ordinary pruning Cleanup sees the current goal bindings; during
-exception unwinding bindings made by the protected goal have already been
-unwound. Cleanup failure is ignored, and an exception already being propagated
-takes precedence over a cleanup exception. Nested cleanups run inside-out.
-
-These predicates are EyeProlog normal-mode extensions and are absent from
-`--iso-strict`. Their implementation is lifecycle-aware: the interactive top
-level can report a remaining choicepoint without speculatively requesting the
-next solution, while abandoning that choicepoint still closes protected
-resources.
-
-## OpenRuleBench portable profile
-
-The `openrulebench/` directory contains a deterministic four-engine adaptation
-for EyeProlog, Trealla, Scryer, and SWI-Prolog. Its default `portable` profile
-keeps the characteristic joins, recursive closures, and WFS cases while
-avoiding benchmark sizes that require multi-gigabyte collectors on some
-engines. Run EyeProlog's complete profile with:
-
-```sh
-./openrulebench/run-eyeprolog.mjs
-```
-
-The benchmark README records the expected answer counts. Timing values are
-machine-dependent; use the same generated profile when comparing engines.
-
-## Strict ISO/IEC 13211-1 core
-
-For portability and conformance work, run the Part 1 core with Technical
-Corrigenda 1–3 in strict mode:
-
-```sh
-eyeprolog --iso-strict
-eyeprolog --iso-strict --goal 'p(X)' program.pl
-```
-
-The equivalent JavaScript option is `isoStrict: true`. Strict mode keeps
-EyeProlog's documented implementation-defined Unicode scalar processor
-character set, while excluding normal-profile language extensions such as Part
-2 module compatibility forms, Part 3 DCG expansion, quads, extra libraries,
-automatic tabling, and non-standard flags/control facilities. Normal mode is
-unchanged.
-
-This README intentionally stays at the project-overview level. The detailed
-implementation reference is [*The Art of EyeProlog*](the-art-of-eyeprolog.md).
-The current Part 1 audit status and closure criteria are recorded in
-[`test/conformance/ISO-COMPLIANCE.md`](test/conformance/ISO-COMPLIANCE.md);
-implementation-defined decisions are indexed in
-[`ISO-IMPLEMENTATION-DEFINED.md`](test/conformance/ISO-IMPLEMENTATION-DEFINED.md). The complete
-vendored WG17 syntax corpus and the strict ISO regression suite run as release
-gates.
-
-The release-facing Part 1 audit ledger has explicit dispositions for its tracked requirements. This implementation evidence is not an independent ISO certification.
-
-## Module and definite clause grammar compatibility profiles
-
-Normal EyeProlog supports the widely used `module/2`, `use_module/1-2`,
-`meta_predicate/1`, and `Module:Goal` interface reflected in later WG17 module
-amendment work. This is a practical module compatibility profile; EyeProlog
-does **not** currently claim a clause-by-clause implementation or certification
-of the complete ISO/IEC 13211-2:2000 module model.
-
-Definite clause grammar support follows the ISO/IEC TS 13211-3 grammar-rule and
-`phrase/2-3` model and is exercised by the conformance corpus. As with Part 1,
-that implementation evidence is not an independent certification of every
-Part 3 requirement. For example:
-
-```prolog
-sentence --> [hello], noun.
-noun --> [world] | [prolog].
-
-%% goal: phrase(sentence, Words)
-```
-
-For a larger bidirectional example, see
-[`examples/dcg-expression-language.pl`](examples/dcg-expression-language.pl).
-It parses precedence-sensitive arithmetic into an AST, evaluates expressions
-with variables, generates tokens back from an AST with only the necessary
-parentheses, round-trips the generated form, and demonstrates `phrase/3`
-remainder handling.  The example uses accumulator nonterminals for
-left-associative operators, so state is handed repeatedly from one nonterminal
-to the next rather than hidden in host code.
-
-Deep finite DCG traversal is kept relational but does not have to consume one
-general solver frame per token.  In particular, the interoperable `... //0`
-helper from `library(iso_ext)` can scan a finite compact list iteratively, and a
-following grammar that is statically known to leave the DCG state unchanged can
-be continued without rebuilding a full clause-resolution frame for every
-suffix.  Open and remainder-producing uses still retain the ordinary DCG
-solutions and backtracking behavior.
+## Links
 
-EyeProlog also adds 135 public library predicate indicators to its 129-entry ISO
-profile. **89 are implemented entirely as ordinary Prolog clauses** in focused
-modules under `src/lib/`; the remaining control predicates, attributed-variable
-primitives, and the transitional finite-domain `library(clpz)` kernel use
-backtrackable host support.
-They are ordinary Prolog modules using EyeProlog's documented module compatibility surface, loaded explicitly by purpose, such as
-`library(lists)`, `library(lambda)`, `library(strings)`, `library(aggregate)`,
-`library(atts)`, or `library(clpz)`.
-Portable text
-predicates use ISO atoms or character lists. The old catch-all
-`library(eyeprolog)` module is no longer needed.
-
-## Trealla and Scryer interoperability
-
-EyeProlog keeps a conservative source-level interoperability profile separate
-from the larger EyeProlog library surface. `library(lists)` follows the common
-Trealla/Scryer organization for predicates such as `member/2`, `memberchk/2`,
-`append/2-3`, `nth0/3-4`, `nth1/3-4`, `length/2`, `maplist/2-8`, and
-`foldl/4-6`. Its `length/2` remains relational: with both arguments variable,
-`length(Xs, N)` enumerates lists of increasing length together with `N = 0, 1,
-2, ...`. Open-ended generation uses the normal memory guard with recovery
-headroom, so an exhausted finite heap is reported as a catchable
-`resource_error(memory)` instead of degenerating into quadratic list checks.
-
-`library(iso_ext)` is also accepted as a common interop module name.
-EyeProlog exports `call_nth/2`, `time/1`, and the DCG helper `... //0` there.
-The latter describes an arbitrary number of input elements and supports the
-nonterminal hand-off benchmark used by the interoperability tests. These common predicates
-may be imported explicitly, while source/CLI/API dependency loading can resolve
-their unqualified forms conservatively. For Trealla-style interactive timing,
-`time/1` is also available directly in the normal EyeProlog runtime; strict ISO
-mode does not expose it.
-`library(lists)`, `library(iso_ext)`, and `library(freeze)` follow the focused
-module organization used by Trealla and Scryer. EyeProlog's legacy
-`library(prologue)` is now a compatibility facade over these canonical modules
-and `library(between)`, so it can be imported before or after the focused
-libraries without duplicate-import errors.
-
-`library(lambda)` follows Scryer's higher-order lambda notation, adapted from
-Ulrich Neumerkel's permissively licensed implementation. Importing it installs
-the `+\` operator and enables closures such as `\X^Goal` and
-`Free+\X^Goal`. Parameters are supplied by `call/N`; variables not listed in
-`Free` are copied afresh for each invocation, while explicitly free variables
-remain shared. For example:
-
-```prolog
-:- use_module(library(lambda)).
-:- use_module(library(lists)).
-
-all_positive(Xs) :- maplist(\X^(X > 0), Xs).
-all_equal(Y, Xs) :- maplist(Y+\X^(X = Y), Xs).
-```
-
-The explicit import is intentional: unlike ordinary predicate autoloading, the
-lambda syntax also changes the active operator table.
-
-Outside `--iso-strict`, an otherwise undefined unqualified call may autoload a
-predicate only when the interop profile has one canonical EyeProlog provider.
-For example, `member/2` autoloads from `library(lists)`, `call_nth/2` from
-`library(iso_ext)`, `call_residue_vars/2` from `library(atts)`, and `between/3`
-from `library(between)`. Use `--no-autoload` to disable this
-convenience. Strict ISO mode never autoloads library predicates.
-
-Use `-w` / `--warnings` to diagnose dependencies outside the interop profile,
-or `--portable` to make such diagnostics fail the run. This catches both
-implementation-specific library names and EyeProlog-only predicates such as
-`set_nth0/4` even when they live in an otherwise common module.
-
-Cross-engine smoke tests live in `test/run-interop.mjs`. With Trealla (`tpl`)
-and Scryer (`scryer-prolog`) installed, run:
-
-```sh
-npm run test:interop
-```
-
-This optional check runs the same portable Towers of Hanoi source under
-EyeProlog, Trealla, and Scryer. The default `npm test` does not require external
-Prolog implementations; it does validate all four generated OpenRuleBench
-source trees and their engine-specific tabling and WFS adaptations. Run those
-fast structural checks separately with `npm run test:openrulebench`.
+- [The Art of EyeProlog](https://eyereasoner.github.io/eyeprolog/the-art-of-eyeprolog) — complete reference
+- [Why EyeProlog?](https://eyereasoner.github.io/eyeprolog/why-eyeprolog) — project scope and design
+- [Playground](https://eyereasoner.github.io/eyeprolog/playground) — run EyeProlog in a browser
+- [Examples](examples) — runnable programs and checked output
+- [ISO conformance audit](test/conformance/ISO-COMPLIANCE.md) — supported Part 1 profile
+- [Conformance report](conformance-report.md) — generated public corpus summary
+- [OpenRuleBench](openrulebench/README.md) — portable benchmark profile
 
 ## Development
 
@@ -393,14 +77,4 @@ npm install
 npm test
 ```
 
-The GitHub test workflow runs the complete suite and an npm package dry-run on
-both the minimum supported Node.js 18 release line and Node.js 24. Publishing
-repeats those release checks before uploading the package.
-
-The runtime JavaScript modules stay flat under `src/`; the existing `src/lib/`
-directory contains the portable Prolog library modules. See
-[`src/ARCHITECTURE.md`](src/ARCHITECTURE.md) for the source-layer boundaries,
-facade modules, dependency rule, and the requirement that architectural cleanup
-must preserve the existing solver hot paths and benchmark performance.
-
 EyeProlog is released under the [MIT License](LICENSE.md).

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.3.78",
+  "version": "1.3.79",
   "description": "EyeProlog turns facts and rules into answers and proofs.",
   "type": "module",
   "main": "./index.js",

package/src/standard-library.js

@@ -69,25 +69,44 @@ export const eyePrologNativeLibraryIndicators = Object.freeze([
   'in/2', 'ins/2', 'all_different/1', 'all_distinct/1', 'nvalue/2', 'sum/3',
   'scalar_product/4', 'tuples_in/2', 'labeling/2', 'label/1',
   'indomain/1', 'lex_chain/1', 'serialized/2', 'global_cardinality/2',
-  'global_cardinality/3', 'circuit/1', 'chain/2', 'element/3', 'zcompare/3',
+  'global_cardinality/3', 'circuit/1', 'cumulative/1', 'cumulative/2',
+  'disjoint2/1', 'automaton/3', 'automaton/8', 'chain/2', 'element/3', 'zcompare/3',
   'fd_var/1', 'fd_inf/2', 'fd_sup/2', 'fd_size/2', 'fd_dom/2',
+  'clpz_t/2', '#=/3', '#</3',
 ]);
 export const eyePrologPortableLibraryIndicators = Object.freeze([
   'sumall/3', 'aggregate_min/5', 'aggregate_max/5',
-  'lt/2', 'gt/2', 'le/2', 'ge/2', 'difference/3',
-  'maplist/2', 'maplist/3', 'maplist/4', 'maplist/5',
-  'maplist/6', 'maplist/7', 'maplist/8', 'between/3',
-  'smallest_divisor_from/3', 'random/3', 'matches/3', 'split/3',
-  'replace/4', 'lowercase/2', 'uppercase/2', 'trim/2', 'number_string/2',
-  'atom_string/2', 'term_string/2', 'append/2', 'append/3', 'string_concat/3', 'contains/2',
-  'matches/2', 'join/3', 'substring/4', 'member/2', 'memberchk/2', 'select/3', 'last/2', 'same_length/2',
-  'nth0/3', 'nth0/4', 'nth1/3', 'nth1/4', 'set_nth0/4', 'take/3', 'drop/3', 'slice/4', 'reverse/2',
-  'length/2', 'sum_list/2', 'min_list/2', 'max_list/2', 'list_to_set/2',
-  'succ/2', 'foldl/4', 'foldl/5', 'foldl/6',
-  'forall/2', 'cfor/3', 'findall/4', 'variant/2', '.../2', 'uuid/3',
+  'lsb/2', 'msb/2', 'popcount/2',
+  'empty_assoc/1', 'assoc_to_list/2', 'get_assoc/3', 'put_assoc/4',
+  'between/3', 'gen_int/1', 'gen_nat/1', 'numlist/2', 'numlist/3', 'repeat/1',
+  'lt/2', 'gt/2', 'le/2', 'ge/2',
+  'difference/3',
+  'seq/3', 'seqq/3',
+  'debug/1', 'debug/3', 'nodebug/1', 'bb_get/2', 'bb_b_put/2',
+  'must_be/2', 'can_be/2', 'instantiation_error/0', 'instantiation_error/1',
+  'domain_error/2', 'domain_error/3', 'type_error/2', 'type_error/3',
+  'representation_error/1', 'resource_error/1', 'call_with_error_context/2',
+  'format/2',
+  'forall/2', 'succ/2', 'cfor/3', 'findall/4', 'variant/2', '.../2',
   '^/3', '^/4', '^/5', '^/6', '^/7', '^/8', '^/9', '^/10',
   '\\/1', '\\/2', '\\/3', '\\/4', '\\/5', '\\/6', '\\/7', '\\/8',
   '+\\/2', '+\\/3', '+\\/4', '+\\/5', '+\\/6', '+\\/7', '+\\/8', '+\\/9',
+  'member/2', 'memberchk/2', 'select/3', 'append/2', 'append/3', 'last/2', 'same_length/2',
+  'nth0/3', 'nth0/4', 'nth1/3', 'nth1/4', 'set_nth0/4', 'take/3', 'drop/3', 'slice/4', 'reverse/2',
+  'length/2', 'maplist/2', 'maplist/3', 'maplist/4', 'maplist/5',
+  'maplist/6', 'maplist/7', 'maplist/8', 'foldl/4', 'foldl/5', 'foldl/6',
+  'sum_list/2', 'min_list/2', 'max_list/2', 'list_to_set/2',
+  'pairs_keys_values/3', 'pairs_keys/2', 'pairs_values/2',
+  'group_pairs_by_key/2', 'map_list_to_pairs/3',
+  'smallest_divisor_from/3',
+  'random/3',
+  'atom_si/1', 'integer_si/1', 'atomic_si/1', 'list_si/1', 'character_si/1',
+  'term_si/1', 'chars_si/1', 'dif_si/2', 'not_si/1', 'when_si/2',
+  'matches/3', 'split/3', 'replace/4', 'lowercase/2', 'uppercase/2', 'trim/2',
+  'number_string/2', 'atom_string/2', 'term_string/2', 'string_concat/3',
+  'contains/2', 'matches/2', 'join/3', 'substring/4',
+  'numbervars/3', 'copy_term_nat/2',
+  'uuid/3',
 ]);
 export const eyePrologLibraryIndicators = Object.freeze([
   ...eyePrologPortableLibraryIndicators,

package/test/run-regression.mjs

@@ -3987,7 +3987,15 @@ function documentationSyncCases() {
     },
     {
       name: 'book EyeProlog library matches runtime registry',
-      run: () => assertArrayEqual(bookEyePrologLibraryNames(), registeredEyePrologLibraryNames(), 'EyeProlog library predicates'),
+      run: () => {
+        assertArrayEqual(bookEyePrologLibraryNames(), registeredEyePrologLibraryNames(), 'EyeProlog library predicates');
+        assertArrayEqual(bookLibraryModuleIssues(), [], 'library module export catalog');
+        const book = fs.readFileSync(path.join(packageRoot, 'the-art-of-eyeprolog.md'), 'utf8');
+        assertIncludes(book, `**${eyePrologLibraryIndicators.length} distinct non-ISO library and normal-extension predicate`, 'library predicate count');
+        assertIncludes(book, `**${eyePrologPortableLibraryIndicators.length} are defined entirely as ordinary Prolog clauses**`, 'portable library count');
+        assertIncludes(book, `**${eyePrologNativeLibraryIndicators.length} use host support**`, 'host-supported library count');
+        assertIncludes(book, `**${createDefaultRegistry().defs.size + eyePrologLibraryIndicators.length} distinct predicate indicators**`, 'combined catalog count');
+      },
     },
     {
       name: 'README cover links to the book and the book documents runtime boundaries',
@@ -3999,11 +4007,10 @@ function documentationSyncCases() {
           '<a href="https://eyereasoner.github.io/eyeprolog/the-art-of-eyeprolog">\n    <img src="book-assets/title-page.svg" alt="Read The Art of EyeProlog"',
           'README cover links to the book',
         );
-        for (const filename of ['src/iso.js', 'src/dcg.js', 'src/atts.js', 'src/standard-library.js',
-          'src/lib/aggregate.pl', 'src/lib/atts.pl', 'src/lib/comparison.pl', 'src/lib/dates.pl',
-          'src/lib/iso_ext.pl', 'src/lib/lists.pl', 'src/lib/primes.pl', 'src/lib/prologue.pl',
-          'src/lib/random.pl', 'src/lib/strings.pl', 'src/lib/uuid.pl',
-          'src/playground-worker.js']) {
+        const documentedSources = ['src/iso.js', 'src/dcg.js', 'src/atts.js', 'src/standard-library.js',
+          ...[...standardLibrarySources.values()].map((entry) => entry.filename),
+          'src/playground-worker.js'];
+        for (const filename of documentedSources) {
           assertEqual(fs.existsSync(path.join(packageRoot, filename)), true, `${filename} exists`);
           assertIncludes(book, filename, `book documents ${filename}`);
         }
@@ -4161,6 +4168,11 @@ function documentationSyncCases() {
         ]) assertIncludes(book, name, `book ${name}`);
         assertIncludes(readme, 'implementation reference is [*The Art of EyeProlog*]', 'README book hand-off');
         assertIncludes(readme, 'test/conformance/ISO-COMPLIANCE.md', 'README concise audit link');
+        assertEqual(readme.split('\n').length <= 100, true, 'README remains a compact entry point');
+        for (const heading of ['## Tabling', '## Cleanup-aware control', '## Strict ISO',
+          '## Module and definite clause grammar', '## Trealla and Scryer interoperability']) {
+          assertNotIncludes(readme, heading, `README delegates ${heading} to the book`);
+        }
         assertEqual(readme.includes('2026-08-23 draft items #73-#76'), false, 'README omits audit-history detail');
         assertIncludes(profile, 'Part 1 processor, syntax, semantic, built-in, and arithmetic', 'Why EyeProlog audit state');
       },
@@ -5119,8 +5131,8 @@ answer(ok) :-
         assertEqual(Boolean(library.get('call_cleanup', 2)), true, 'call_cleanup/2 is an EyeProlog cleanup control');
         assertEqual(registry.get('setup_call_cleanup', 3), null, 'setup_call_cleanup/3 is absent from the ISO registry');
         assertEqual(Boolean(library.get('setup_call_cleanup', 3)), true, 'setup_call_cleanup/3 is an EyeProlog cleanup control');
-        assertEqual(registeredNativeEyePrologLibraryNames().length, 49, 'public native EyeProlog builtin count');
-        assertEqual(eyePrologPortableLibraryIndicators.length, 87, 'portable Prolog library count');
+        assertEqual(registeredNativeEyePrologLibraryNames().length, 57, 'public host-supported EyeProlog library count');
+        assertEqual(eyePrologPortableLibraryIndicators.length, 135, 'portable Prolog library count');
         assertEqual(eyePrologInteropLibraryIndicators.length, 30, 'cross-implementation interop profile count');
         assertEqual(eyePrologInteropLibraryModules.join(','), 'lists,iso_ext,lambda,atts,freeze', 'common explicit library module profile');
         assertEqual(eyePrologInteropAutoload['member/2'], 'lists', 'member/2 canonical autoload');
@@ -5130,9 +5142,9 @@ answer(ok) :-
         assertEqual(eyePrologInteropAutoload['time/1'], 'iso_ext', 'time/1 canonical interop autoload');
         assertEqual(eyePrologInteropAutoload['.../2'], 'iso_ext', '.../2 canonical interop autoload');
         assertEqual(eyePrologInteropAutoload['set_nth0/4'] ?? null, null, 'EyeProlog-only set_nth0/4 is not autoloadable');
-        assertEqual(eyePrologNativeLibraryIndicators.length, 49, 'native host library count');
+        assertEqual(eyePrologNativeLibraryIndicators.length, 57, 'host-supported library count');
         assertEqual(eyePrologNativeLibraryIndicators.slice(0, 3).join(','), 'call_nth/2,freeze/2,dif/2', 'control and constraint predicates requiring host support');
-        assertEqual(eyePrologLibraryIndicators.length, 136, 'complete EyeProlog library surface');
+        assertEqual(eyePrologLibraryIndicators.length, 192, 'complete non-ISO EyeProlog library surface');
         assertEqual(registry.get('eyeprolog__call_nth', 2), null, 'private call_nth adapter is absent from ISO registry');
         assertEqual(Boolean(library.get('eyeprolog__call_nth', 2)), true, 'private call_nth adapter is registered for EyeProlog');
         assertEqual(Boolean(library.get('eyeprolog__call_residue_vars', 2)), true, 'private call_residue_vars adapter is registered for EyeProlog');
@@ -6292,7 +6304,45 @@ function bookBuiltinNames() {
 
 function bookEyePrologLibraryNames() {
   const book = fs.readFileSync(path.join(packageRoot, 'the-art-of-eyeprolog.md'), 'utf8');
-  return documentedBuiltinNames(between(book, '<!-- eyeprolog-library-catalog:start -->', '<!-- eyeprolog-library-catalog:end -->'), 2);
+  const iso = new Set(registeredBuiltinNames());
+  return documentedBuiltinNames(
+    between(book, '<!-- eyeprolog-library-catalog:start -->', '<!-- eyeprolog-library-catalog:end -->'),
+    2,
+  ).filter((indicator) => !iso.has(indicator));
+}
+
+function bookLibraryModuleIssues() {
+  const book = fs.readFileSync(path.join(packageRoot, 'the-art-of-eyeprolog.md'), 'utf8');
+  const section = between(book, '<!-- eyeprolog-library-catalog:start -->', '<!-- eyeprolog-library-catalog:end -->');
+  const documented = new Map();
+  for (const line of section.split('\n')) {
+    const match = line.match(/^\|\s*`library\(([^)`]+)\)`\s*\|/);
+    if (match == null) continue;
+    documented.set(match[1], documentedBuiltinNames(line, 2));
+  }
+
+  const issues = [];
+  for (const [moduleName, entry] of standardLibrarySources) {
+    const parsed = Program.parse(entry.source);
+    const definition = parsed.modules.get(moduleName);
+    if (definition == null) {
+      issues.push(`missing module declaration for ${moduleName}`);
+      continue;
+    }
+    const actual = [...definition.exports.keys()].sort();
+    const expected = documented.get(moduleName);
+    if (expected == null) {
+      issues.push(`book catalog omits library(${moduleName})`);
+      continue;
+    }
+    if (JSON.stringify(expected) !== JSON.stringify(actual)) {
+      issues.push(`library(${moduleName}) exports: expected ${actual.join(', ')}, documented ${expected.join(', ')}`);
+    }
+  }
+  for (const moduleName of documented.keys()) {
+    if (!standardLibrarySources.has(moduleName)) issues.push(`book catalogs unknown library(${moduleName})`);
+  }
+  return issues.sort();
 }
 
 function bookBuiltinSummary() {

package/the-art-of-eyeprolog.md

@@ -6211,16 +6211,18 @@ so side effects occur in Prolog execution order.
 
 ### The EyeProlog library
 
-EyeProlog exposes **135 library predicate indicators** in addition to the 129
-indicators in its isolated ISO profile. **89 are defined entirely as ordinary
-Prolog clauses** in focused modules under `src/lib/`. The remaining public
-relations use small private host adapters where control, constraints, or host
-observability cannot be expressed by ordinary clauses alone; `time/1` is one
-such relation. The resulting normal EyeProlog language surface is therefore
-**264 public predicate indicators**. Most library relations remain module source
-clauses over private adapters. `time/1` is additionally registered directly in
-the normal EyeProlog runtime so Trealla-style timing works at the interactive
-top level without an import; it is absent from the strict ISO registry.
+EyeProlog exposes **192 distinct non-ISO library and normal-extension predicate
+indicators** in addition to the 129 indicators in its isolated ISO profile.
+**135 are defined entirely as ordinary Prolog clauses** in focused modules under
+`src/lib/`; **57 use host support** for control, attributed variables,
+constraints, or observability. The ISO and library catalogs therefore cover
+**321 distinct predicate indicators**. Normal-mode controls and observability
+relations that do not belong to a library, such as `call_cleanup/2`,
+`setup_call_cleanup/3`, `statistics/0,2`, and `tnot/1`, are documented in their
+own sections rather than counted as library predicates. `time/1` is additionally
+registered directly in the normal runtime so Trealla-style timing works at the
+interactive top level without an import; it is absent from the strict ISO
+registry.
 
 The sources are `src/lib/aggregate.pl`, `src/lib/arithmetic.pl`,
 `src/lib/assoc.pl`, `src/lib/atts.pl`, `src/lib/between.pl`,
@@ -6256,22 +6258,33 @@ between solution branches.
 
 <!-- eyeprolog-library-catalog:start -->
 
-| Module | Exported predicate indicators |
-| --- | --- |
-| `library(aggregate)` | `sumall/3`, `aggregate_min/5`, `aggregate_max/5` |
-| `library(atts)` | `put_atts/2`, `get_atts/2`, `put_attr/3`, `get_attr/3`, `del_attr/2`, `term_attributed_variables/2`, `call_residue_vars/2` |
-| `library(clpz)` | `#>/2`, `#</2`, `#>=/2`, `#=</2`, `#=/2`, `#\=/2`, `#\/1`, `#<==>/2`, `#==>/2`, `#<==/2`, `#\//2`, `#\/2`, `#/\/2`, `in/2`, `ins/2`, `all_different/1`, `all_distinct/1`, `nvalue/2`, `sum/3`, `scalar_product/4`, `tuples_in/2`, `labeling/2`, `label/1`, `indomain/1`, `lex_chain/1`, `serialized/2`, `global_cardinality/2`, `global_cardinality/3`, `circuit/1`, `chain/2`, `element/3`, `zcompare/3`, `fd_var/1`, `fd_inf/2`, `fd_sup/2`, `fd_size/2`, `fd_dom/2` |
-| `library(comparison)` | `lt/2`, `gt/2`, `le/2`, `ge/2` |
-| `library(dates)` | `difference/3` |
-| `library(iso_ext)` | `call_nth/2`, `countall/2`, `forall/2`, `succ/2`, `cfor/3`, `findall/4`, `variant/2`, `time/1`, `.../2` |
-| Normal runtime extension | `dif/2` |
-| `library(lambda)` | `^/3`, `^/4`, `^/5`, `^/6`, `^/7`, `^/8`, `^/9`, `^/10`, `\/1`, `\/2`, `\/3`, `\/4`, `\/5`, `\/6`, `\/7`, `\/8`, `+\/2`, `+\/3`, `+\/4`, `+\/5`, `+\/6`, `+\/7`, `+\/8`, `+\/9` |
-| `library(lists)` | `member/2`, `memberchk/2`, `select/3`, `append/2`, `append/3`, `last/2`, `same_length/2`, `nth0/3`, `nth0/4`, `nth1/3`, `nth1/4`, `reverse/2`, `length/2`, `maplist/2`, `maplist/3`, `maplist/4`, `maplist/5`, `maplist/6`, `maplist/7`, `maplist/8`, `foldl/4`, `foldl/5`, `foldl/6`, `sum_list/2`, `min_list/2`, `max_list/2`, `list_to_set/2`, `set_nth0/4`, `take/3`, `drop/3`, `slice/4` |
-| `library(primes)` | `smallest_divisor_from/3` |
-| `library(prologue)` | `member/2`, `append/3`, `length/2`, `between/3`, `select/3`, `succ/2`, `maplist/2`, `maplist/3`, `maplist/4`, `maplist/5`, `maplist/6`, `maplist/7`, `maplist/8`, `nth0/3`, `nth0/4`, `nth1/3`, `nth1/4`, `call_nth/2`, `freeze/2`, `foldl/4`, `foldl/5`, `foldl/6`, `countall/2` |
-| `library(random)` | `random/3` |
-| `library(strings)` | `matches/3`, `split/3`, `replace/4`, `lowercase/2`, `uppercase/2`, `trim/2`, `number_string/2`, `atom_string/2`, `term_string/2`, `string_concat/3`, `contains/2`, `matches/2`, `join/3`, `substring/4` |
-| `library(uuid)` | `uuid/3` |
+| Module | Exported predicate indicators | Primary role |
+| --- | --- | --- |
+| `library(aggregate)` | `sumall/3`, `aggregate_min/5`, `aggregate_max/5` | Aggregation |
+| `library(arithmetic)` | `lsb/2`, `msb/2`, `popcount/2` | CLP(Z) arithmetic support |
+| `library(assoc)` | `empty_assoc/1`, `assoc_to_list/2`, `get_assoc/3`, `put_assoc/4` | Association lists used by CLP(Z) |
+| `library(atts)` | `put_atts/2`, `get_atts/2`, `put_attr/3`, `get_attr/3`, `del_attr/2`, `term_attributed_variables/2`, `call_residue_vars/2` | Attributed variables |
+| `library(between)` | `between/3`, `gen_int/1`, `gen_nat/1`, `numlist/2`, `numlist/3`, `repeat/1` | Integer generation |
+| `library(clpz)` | `#>/2`, `#</2`, `#>=/2`, `#=</2`, `#=/2`, `#\=/2`, `#\/1`, `#<==>/2`, `#==>/2`, `#<==/2`, `#\//2`, `#\/2`, `#/\/2`, `in/2`, `ins/2`, `all_different/1`, `all_distinct/1`, `nvalue/2`, `sum/3`, `scalar_product/4`, `tuples_in/2`, `labeling/2`, `label/1`, `indomain/1`, `lex_chain/1`, `serialized/2`, `global_cardinality/2`, `global_cardinality/3`, `circuit/1`, `cumulative/1`, `cumulative/2`, `disjoint2/1`, `element/3`, `automaton/3`, `automaton/8`, `zcompare/3`, `chain/2`, `fd_var/1`, `fd_inf/2`, `fd_sup/2`, `fd_size/2`, `fd_dom/2`, `clpz_t/2`, `#=/3`, `#</3` | Constraint logic programming over integers; the final three indicators support reified compatibility libraries |
+| `library(comparison)` | `lt/2`, `gt/2`, `le/2`, `ge/2` | Generic comparison |
+| `library(dates)` | `difference/3` | ISO duration differences |
+| `library(dcgs)` | `phrase/2`, `phrase/3`, `seq/3`, `seqq/3` | DCG compatibility; `seq/3` and `seqq/3` are declared as `seq //1` and `seqq //1` |
+| `library(debug)` | `debug/1`, `debug/3`, `nodebug/1`, `bb_get/2`, `bb_b_put/2` | Scryer compatibility and backtrackable-blackboard support |
+| `library(error)` | `must_be/2`, `can_be/2`, `instantiation_error/0`, `instantiation_error/1`, `domain_error/2`, `domain_error/3`, `type_error/2`, `type_error/3`, `representation_error/1`, `resource_error/1`, `call_with_error_context/2` | Error checking and construction |
+| `library(format)` | `format/2` | Formatted output used by bundled libraries |
+| `library(freeze)` | `freeze/2` | Delayed goals |
+| `library(iso_ext)` | `call_nth/2`, `countall/2`, `forall/2`, `succ/2`, `cfor/3`, `findall/4`, `variant/2`, `time/1`, `.../2` | Common ISO extensions |
+| Normal runtime extension | `dif/2` | Delayed disequality; available without a library import |
+| `library(lambda)` | `^/3`, `^/4`, `^/5`, `^/6`, `^/7`, `^/8`, `^/9`, `^/10`, `\/1`, `\/2`, `\/3`, `\/4`, `\/5`, `\/6`, `\/7`, `\/8`, `+\/2`, `+\/3`, `+\/4`, `+\/5`, `+\/6`, `+\/7`, `+\/8`, `+\/9` | Higher-order lambda notation |
+| `library(lists)` | `member/2`, `memberchk/2`, `select/3`, `append/2`, `append/3`, `last/2`, `same_length/2`, `nth0/3`, `nth0/4`, `nth1/3`, `nth1/4`, `reverse/2`, `length/2`, `maplist/2`, `maplist/3`, `maplist/4`, `maplist/5`, `maplist/6`, `maplist/7`, `maplist/8`, `foldl/4`, `foldl/5`, `foldl/6`, `sum_list/2`, `min_list/2`, `max_list/2`, `list_to_set/2`, `set_nth0/4`, `take/3`, `drop/3`, `slice/4` | List relations |
+| `library(pairs)` | `pairs_keys_values/3`, `pairs_keys/2`, `pairs_values/2`, `group_pairs_by_key/2`, `map_list_to_pairs/3` | Key-value pair support |
+| `library(primes)` | `smallest_divisor_from/3` | Prime factor support |
+| `library(prologue)` | `member/2`, `append/3`, `length/2`, `between/3`, `select/3`, `succ/2`, `maplist/2`, `maplist/3`, `maplist/4`, `maplist/5`, `maplist/6`, `maplist/7`, `maplist/8`, `nth0/3`, `nth0/4`, `nth1/3`, `nth1/4`, `call_nth/2`, `freeze/2`, `foldl/4`, `foldl/5`, `foldl/6`, `countall/2` | Legacy facade over canonical focused modules |
+| `library(random)` | `random/3` | Pure state-threaded random generation |
+| `library(si)` | `atom_si/1`, `integer_si/1`, `atomic_si/1`, `list_si/1`, `character_si/1`, `term_si/1`, `chars_si/1`, `dif_si/2`, `not_si/1`, `when_si/2` | Sufficient-instantiation checks used by CLP(Z) |
+| `library(strings)` | `matches/3`, `split/3`, `replace/4`, `lowercase/2`, `uppercase/2`, `trim/2`, `number_string/2`, `atom_string/2`, `term_string/2`, `string_concat/3`, `contains/2`, `matches/2`, `join/3`, `substring/4` | Text relations |
+| `library(terms)` | `numbervars/3`, `copy_term_nat/2` | Term operations used by bundled libraries |
+| `library(uuid)` | `uuid/3` | Pure state-threaded UUID generation |
 
 <!-- eyeprolog-library-catalog:end -->