The runtime is intentionally layered so semantic modules do not depend back on higher-level frontends.
term.js, number-value.js,
syntax-scan.js, parser.js, write.js, errors.js.program.js, source-expansion.js, plus
program-analysis.js and program-indexing.js. Static recursion/Datalog/WFS classification lives in
program-analysis.js; compact clauses and candidate indexes live in
program-indexing.js. Recording one clause into its group’s indexes is
program-indexing.js’s indexGroupClause, and every path that adds a
clause – source loading, the public indexClause, assertz/1, and a full
rebuildGroupIndexes replay – goes through it, so a group built by loading
and the same group after a rebuild cannot disagree. It must not touch
clause.head on the compact-binary path, whose head term is materialized
lazily.solver.js, cleanup.js, io.js, datalog.js, wfs.js.
datalog-common.js owns what the two Datalog evaluators share: scalar row
keying and the per-argument candidate-bucket narrowing both index their
relations with. Their fixpoint algorithms and relation storage stay in their
own modules. Positive Datalog compiles clause variables to numeric slots
and joins through array bindings; WFS retains its persistent Map bindings.
Candidate selection has a direct entry point for each binding representation
so their inner loops do not dispatch through a binding-store abstraction.
cleanup.js owns lifecycle-aware disposal of protected builtin
iterators and registers the normal-profile cleanup controls without making
solver.js depend back on the language registry.iso.js, iso-arithmetic.js, dcg.js, atts-host.js,
standard-library.js, the module-owned src/<module>-host.js adapters, and
the public Prolog modules under src/lib/.execute.js, repl.js, cli.js, quads.js,
explain.js, and the playground worker.explain.js owns both proof construction and proof-certificate verification.
Verification walks the supplied certificate and checks source-clause steps against
the parsed Program; it does not call the solver to rediscover the proof.
Built-in and abstract library nodes are explicit trust boundaries, while expanded
proofs expose bundled Prolog-library clauses as ordinary source steps.
Proof nodes share the runtime terms they resolve. Runtime terms are structurally
immutable, so a ground subtree already is the snapshot a proof needs, and
resolveForProof copies only the ancestors of an argument that variable
resolution actually changed. Nothing anywhere may rewrite a term in place.
iso.js and program.js remain facade modules for their existing exports, so
this refactor does not change the public JavaScript API.
Dependencies should point down or sideways within a layer, never back from a
kernel component into the ISO registry or a frontend. In particular,
errors.js owns PrologError and HaltSignal; DCG expansion can therefore
report processor errors without importing iso.js and creating an
iso.js <-> dcg.js cycle.
term.js also owns the generic annotated-variable storage carried by Env.
Annotations are persistent across Env.clone() and therefore backtrack with the
substitution. Language services may attach immutable constraint descriptors,
but the unconstrained unification hot path only performs a null check; descriptor
validation and reindexing run only in environments that actually contain
annotations. Descriptors can optionally define logical subsumption so the
store retains only its strongest pending constraints. dif/2 is the first
descriptor-based user of this mechanism.
atts-host.js layers Prolog-visible attributed variables over that same persistent
environment. Per-module attributes follow the current variable representative.
When an attributed variable is about to be bound, the solver runs that module’s
verify_attributes/3 against the still-unbound representative; only a successful
hook permits the binding, and any goals returned in the third argument are queued
immediately after it. Scryer’s Prolog library(clpz) uses this pre-bind/post-bind
protocol directly for its domains and propagators.
Env also owns the small generic backtrackable blackboard used by Scryer-style
libraries. Blackboard maps are shared by clones and copied only on write, so
bb_b_put/2 follows ordinary Prolog backtracking without any CLP(Z)-specific
state in the VM. Its private runtime bridge is owned by iso_ext-host.js, matching
Scryer’s canonical library(iso_ext) ownership; library(debug) may re-export
that interface for EyeProlog compatibility without owning another implementation.
source-expansion.js is the explicit compile-time execution boundary. When an
already-loaded term_expansion/2 or goal_expansion/2 hook exists, program
preparation invokes it with a fresh bounded Solver against the partially built
program. solver.js therefore imports clause-selection primitives directly from
program-indexing.js rather than importing the program.js facade. This is the
one deliberate preparation-to-execution service edge and keeps the JavaScript
import graph acyclic while avoiding a second meta-interpreter solely for source
expansion. expansion-builtins.js provides the lower-level expand_term/2 DCG
service without depending on Solver.
The JavaScript runtime stays flat directly under src/; src/lib/ contains the
public Prolog library sources. Runtime-dependent library primitives follow a
one-module/one-host convention: a private eyeprolog__* adapter referenced by
src/lib/foo.pl must be registered from src/foo-host.js.
worker-bridge.js holds the one piece those hosts share rather than own: the
synchronous SharedArrayBuffer/Atomics transport that lets http-host.js and
sockets-host.js drive Node’s asynchronous I/O from inside the synchronous
solver. Each host still supplies its own request vocabulary and its own error
translation, so the transport carries no library-specific semantics. Pure Prolog modules,
such as library(freeze), intentionally have no host file. standard-library.js
registers these module hosts without owning their semantics. The architecture
test rejects JavaScript import cycles, verifies private adapter ownership, freezes
the current Scryer export surface for all 32 overlapping bundled modules, and
rejects the retired library-host.js and scryer-compat.js grab bags. Cleanup
lifecycle hooks are installed from the public API and CLI entry paths, so the
execution layer remains acyclic.
Architecture changes must not add runtime strategy objects, callbacks, or extra dispatch in solver hot paths. Existing scalar/indexed solver paths stay as direct function calls. Candidate indexing is separated physically but retains the same data structures and selection functions.
Generic solver fast paths remain co-located in solver.js until a split can
demonstrate performance parity. Module-specific acceleration belongs to the
matching *-host.js adapter: clpz-host.js and clpb-host.js, for example,
construct native propagation/search plans while their Prolog modules retain
validation, residual constraints, and portable fallbacks. A cleaner file layout
is not worth a runtime regression, so such splits must retain benchmark parity.
Hot paths follow one allocation discipline: the state a walk or a comparison
needs only for its hard case – a cycle guard, a traversal stack, a variable
pairing – is allocated when that case actually appears rather than on entry.
deref, variantTerms, and goalHeadTermsCannotMatch therefore decide the
shallow, acyclic, scalar-argument case, which is the overwhelming majority of
their calls, without allocating anything. A key a table or an index derives
from a term is built once into one fragment array for the whole term: a key
composed from a key per subterm makes recording one answer quadratic in that
answer’s own size.
Performance claims use npm test’s own elapsed time across the full corpus,
not predicate, inference, or host-call counts as a substitute for elapsed
time, and not a separate wall-clock benchmark harness.
src/lib/json.pl is a pure Prolog DCG adapted from the BSD-licensed Scryer/Trealla JSON library, with Unicode-scalar handling for JSON UTF-16 surrogate escapes. src/lib/http.pl owns HTTP option normalization, convenience predicates, request parsing, and the small server facade. Node HTTP/HTTPS client I/O is isolated in src/http-host.js and src/http-worker.js, following the same module-owned host-adapter convention as sockets, files, crypto, and other runtime-dependent libraries. The worker returns response metadata first and retains the response body behind a body id; the host stream pulls bounded chunks through the bridge on demand, so response size is no longer bounded by the RPC buffer and early close/1 can discard the remaining transport body.