eyeprolog 1.3.66 → 1.3.67

package/README.md

@@ -147,6 +147,26 @@ 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 the CLP(Z) migration
+
+`library(atts)` now exposes Scryer-style attributed-variable operations on the
+same persistent `Env` machinery introduced for `dif/2`: `put_atts/2`,
+`get_atts/2`, `put_attr/3`, `get_attr/3`, `del_attr/2`, and
+`term_attributed_variables/2`. `:- attribute ...` declarations are accepted,
+`verify_attributes/3` is invoked 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).
+
+This is the first migration stage toward reusing Markus Triska's MIT-licensed
+[Scryer `library(clpz)`](https://github.com/mthom/scryer-prolog/blob/master/src/lib/clpz.pl)
+instead of maintaining a separate constraint solver in `src/clpz.js`. The
+current CLP(Z) implementation remains active while compatibility gaps such as
+Scryer's compile-time term/goal expansion and supporting libraries are closed.
+The staged plan and exact compatibility boundary are documented in
+[`src/CLPZ-MIGRATION.md`](src/CLPZ-MIGRATION.md).
+
 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
@@ -275,13 +295,14 @@ 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.
 
-EyeProlog also adds 129 public library predicate indicators to its 129-entry ISO
-profile. **88 are implemented entirely as ordinary Prolog clauses** in focused
-modules under `src/lib/`; the remaining control predicates and finite-domain
-`library(clpz)` kernel use backtrackable host support.
+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)`, or
-`library(clpz)`.
+`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.

package/examples/attributed-variables.pl

@@ -0,0 +1,40 @@
+% Scryer-style attributed variables on EyeProlog's annotated-variable runtime.
+%
+% The attribute declaration is intentionally the same shape used by
+% library(atts) clients such as Scryer's CLP(Z). verify_attributes/3 runs before
+% an attributed variable is bound; goals it returns run after the binding.
+
+:- use_module(library(atts)).
+:- attribute required/1.
+
+%% goal: accepts_required_value(ok)
+%% goal: alias_preserves_attribute(ok)
+
+attach_required(Variable, Value) :-
+    put_atts(Variable, required(Value)).
+
+verify_attributes(Variable, Other, Goals) :-
+    ( get_atts(Variable, required(Value)) ->
+        ( var(Other) ->
+            put_atts(Other, required(Value)),
+            Goals = []
+        ; Goals = [required_value(Other, Value)] )
+    ; Goals = [] ).
+
+required_value(Value, Value).
+
+accepts_required_value(ok) :-
+    attach_required(X, 7),
+    X = 7.
+
+alias_preserves_attribute(ok) :-
+    attach_required(X, ready),
+    X = Y,
+    get_atts(Y, required(ready)),
+    Y = ready.
+
+% The REPL uses the conventional attribute_goals//1 hook to project remaining
+% attributes as residual goals.
+attribute_goals(X) -->
+    { get_atts(X, required(Value)) },
+    [required(X, Value)].

package/examples/output/attributed-variables.pl

@@ -0,0 +1,2 @@
+accepts_required_value(ok).
+alias_preserves_attribute(ok).

package/package.json

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

package/playground.html

@@ -446,6 +446,7 @@
           "ancestor",
           "animal",
           "annotation",
+          "attributed-variables",
           "auroracare",
           "backward",
           "basic-monadic",

package/src/ARCHITECTURE.md

@@ -15,7 +15,7 @@ higher-level frontends.
    `clpz.js`. `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.
-4. **Language services** — `iso.js`, `iso-arithmetic.js`, `dcg.js`,
+4. **Language services** — `iso.js`, `iso-arithmetic.js`, `dcg.js`, `atts.js`,
    `standard-library.js`, and `src/lib/`.
 5. **Frontends/tools** — `execute.js`, `repl.js`, `cli.js`, `quads.js`,
    `explain.js`, and the playground worker.
@@ -36,7 +36,17 @@ 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. `dif/2` is the first user of this mechanism.
+annotations. `dif/2` is the first descriptor-based user of this mechanism.
+
+`atts.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. This pre-bind/post-bind split is the compatibility boundary
+needed by Scryer's `library(atts)` and `library(clpz)`. The current CLP(Z)-specific
+`Env._clpz` store remains transitional until the Scryer Prolog implementation can
+replace it without losing test or performance parity; see `src/CLPZ-MIGRATION.md`.
 
 The JavaScript runtime stays flat directly under `src/`; the existing `src/lib/`
 contains Prolog library sources rather than JavaScript runtime modules. The architecture

package/src/CLPZ-MIGRATION.md

@@ -0,0 +1,61 @@
+# CLP(Z) migration toward Scryer's Prolog implementation
+
+EyeProlog's current `library(clpz)` has a Prolog API in `src/lib/clpz.pl` and a
+CLP(Z)-specific propagation store in `src/clpz.js`. The long-term target is to
+reuse Markus Triska's MIT-licensed [`clpz.pl` from Scryer
+Prolog](https://github.com/mthom/scryer-prolog/blob/master/src/lib/clpz.pl) and
+keep the JavaScript runtime responsible for generic Prolog VM facilities rather
+than a second finite-domain solver.
+
+## Stage 1: attributed-variable substrate
+
+This stage is implemented. `Env` carries persistent per-module Prolog
+attributes in addition to the generic constraint descriptors introduced for
+`dif/2`. `src/atts.js` and `library(atts)` expose the operations required by the
+Scryer style: `put_atts/2`, `get_atts/2`, `put_attr/3`, `get_attr/3`,
+`del_attr/2`, and `term_attributed_variables/2`. The parser accepts the
+`attribute` declaration operator, Scryer-style comma-separated
+`:- attribute a/1, b/0.` directives, and `op/3` entries in module export lists.
+
+The important unification protocol is also implemented. Before an attributed
+variable is bound to a nonvariable, or before two variables carrying attributes
+for the same owner module are aliased, the solver invokes the owner's
+`verify_attributes/3`. A failed hook rejects the unification. Goals returned in
+the third argument are queued only after the binding succeeds. Aliasing an
+attributed variable with a plain variable transfers the persistent attribute map
+to the surviving representative, which is equivalent to Scryer's CLP(Z)
+`verify_attributes/3` transfer branch and avoids a recursive hook call while
+entering the hook itself.
+
+The substrate is covered by regressions for lookup, alias transfer, conflicting
+attributes, post-binding goals, backtracking, `term_attributed_variables/2`, and
+REPL projection through the conventional module `attribute_goals//1` hook.
+`examples/attributed-variables.pl` is the runnable source-level example.
+
+## What still prevents a drop-in Scryer `clpz.pl`
+
+The upstream solver is not only an attributed-variable client. It also relies on
+compile-time facilities that EyeProlog does not yet provide generically:
+
+- user-defined `term_expansion/2` and `goal_expansion/2` during module loading;
+- the generated predicates at the end of Scryer's `clpz.pl` and its custom Duo
+  DCG `++>` expansion;
+- the supporting Scryer library surface (`assoc`, `pairs`, `between`, `dcgs`,
+  `terms`, `error`, `si`, `freeze`, `arithmetic`, `debug`, and `format`) at the
+  interfaces expected by that source;
+
+These are compatibility gaps, not reasons to add more CLP(Z)-specific code to
+`term.js` or `solver.js`.
+
+## Migration rule
+
+`src/clpz.js` remains the active implementation until an upstream-based Prolog
+solver passes the existing EyeProlog CLP(Z) corpus and the selected Scryer CLP(Z)
+regressions. During the transition it is the behavioral reference, not the
+architecture to extend. New generic VM work should go into attributed variables,
+term/goal expansion, or reusable library support where possible.
+
+Once the upstream source loads and reaches parity, remove the corresponding
+`eyeprolog__clpz_*` adapters and the `_clpz` store in one or more reviewable
+steps. Keep the upstream copyright and MIT license notice intact and keep local
+patches small enough that future Scryer updates can be diffed mechanically.

package/src/atts.js

@@ -0,0 +1,224 @@
+// Generic attributed-variable bridge for Prolog libraries.
+//
+// The storage is owned by Env so attributes backtrack with substitutions. This
+// module exposes the small atts interface used by Scryer libraries. Attribute
+// verification itself is scheduled by term.js and executed by Solver before a
+// binding is committed; goals returned by verify_attributes/3 run immediately
+// after the binding.
+
+import {
+  ATOM, COMPOUND, VAR, atom, compound, deref, listFromItems,
+  properListItems, unify, variable,
+} from './term.js';
+import { PrologError } from './errors.js';
+
+function callerModule(goal) {
+  return goal.module ?? 'user';
+}
+
+function attributeSignature(term) {
+  if (term.type === ATOM) return { name: term.name, arity: 0 };
+  if (term.type === COMPOUND) return { name: term.name, arity: term.arity };
+  return null;
+}
+
+function normalizedAttribute(term, env) {
+  let resolved = deref(term, env);
+  let mode = 'put';
+  if (resolved.type === COMPOUND && resolved.arity === 1 && (resolved.name === '+' || resolved.name === '-')) {
+    mode = resolved.name === '-' ? 'delete' : 'put';
+    resolved = deref(resolved.args[0], env);
+  }
+  if (resolved.type === VAR) throw new PrologError('instantiation_error');
+  const signature = attributeSignature(resolved);
+  if (signature == null) throw new PrologError('type_error(callable)', resolved);
+  return { mode, attribute: resolved, ...signature };
+}
+
+function putOne(next, variableTerm, owner, attributeTerm) {
+  const variableValue = deref(variableTerm, next);
+  if (variableValue.type !== VAR) throw new PrologError('uninstantiation_error', variableValue);
+  const normalized = normalizedAttribute(attributeTerm, next);
+  if (normalized.mode === 'delete') {
+    next.deletePrologAttribute(variableValue.name, owner, normalized.name, normalized.arity);
+    return;
+  }
+  next.putPrologAttribute(variableValue.name, owner, normalized.attribute);
+}
+
+function* putAttsBuiltin({ goal, env }) {
+  const next = env.clone();
+  const owner = callerModule(goal);
+  const variableTerm = deref(goal.args[0], next);
+  if (variableTerm.type !== VAR) throw new PrologError('uninstantiation_error', variableTerm);
+  const list = properListItems(goal.args[1], next);
+  if (list != null) {
+    for (const attribute of list) putOne(next, variableTerm, owner, attribute);
+  } else {
+    putOne(next, variableTerm, owner, goal.args[1]);
+  }
+  yield next;
+}
+
+function* getAttsBuiltin({ goal, env }) {
+  const variableTerm = deref(goal.args[0], env);
+  if (variableTerm.type !== VAR) throw new PrologError('uninstantiation_error', variableTerm);
+  const owner = callerModule(goal);
+  const pattern = deref(goal.args[1], env);
+  const attributes = env.prologAttributes(variableTerm.name, owner);
+  if (pattern.type === VAR) {
+    if (attributes.length === 0) return;
+    const next = env.clone();
+    if (unify(goal.args[1], listFromItems(attributes), next)) yield next;
+    return;
+  }
+
+  let mode = 'present';
+  let inner = pattern;
+  if (pattern.type === COMPOUND && pattern.arity === 1 && (pattern.name === '+' || pattern.name === '-')) {
+    mode = pattern.name === '-' ? 'absent' : 'present';
+    inner = deref(pattern.args[0], env);
+  }
+  if (inner.type === VAR) throw new PrologError('instantiation_error');
+  const signature = attributeSignature(inner);
+  if (signature == null) throw new PrologError('type_error(callable)', inner);
+  const stored = env.getPrologAttribute(variableTerm.name, owner, signature.name, signature.arity);
+  if (mode === 'absent') {
+    if (stored == null) yield env.clone();
+    return;
+  }
+  if (stored == null) return;
+  const next = env.clone();
+  if (unify(inner, stored, next, { skipVariableConstraints: true })) yield next;
+}
+
+function attributeName(term, env) {
+  const resolved = deref(term, env);
+  if (resolved.type === VAR) throw new PrologError('instantiation_error');
+  if (resolved.type !== ATOM) throw new PrologError('type_error(atom)', resolved);
+  return resolved.name;
+}
+
+function* putAttrBuiltin({ goal, env }) {
+  const next = env.clone();
+  const owner = callerModule(goal);
+  const variableTerm = deref(goal.args[0], next);
+  if (variableTerm.type !== VAR) throw new PrologError('uninstantiation_error', variableTerm);
+  const name = attributeName(goal.args[1], next);
+  next.putPrologAttribute(variableTerm.name, owner, compound(name, [goal.args[2]]));
+  yield next;
+}
+
+function* getAttrBuiltin({ goal, env }) {
+  const variableTerm = deref(goal.args[0], env);
+  if (variableTerm.type !== VAR) return;
+  const owner = callerModule(goal);
+  const name = attributeName(goal.args[1], env);
+  const stored = env.getPrologAttribute(variableTerm.name, owner, name, 1);
+  if (stored == null) return;
+  const next = env.clone();
+  if (unify(goal.args[2], stored.args[0], next, { skipVariableConstraints: true })) yield next;
+}
+
+function* delAttrBuiltin({ goal, env }) {
+  const next = env.clone();
+  const variableTerm = deref(goal.args[0], next);
+  if (variableTerm.type !== VAR) { yield next; return; }
+  const owner = callerModule(goal);
+  const name = attributeName(goal.args[1], next);
+  next.deletePrologAttribute(variableTerm.name, owner, name, null);
+  yield next;
+}
+
+function collectTermVariables(term, env) {
+  const result = [];
+  const seen = new Set();
+  const stack = [term];
+  while (stack.length) {
+    const current = deref(stack.pop(), env);
+    if (current.type === VAR) {
+      if (!seen.has(current.name)) {
+        seen.add(current.name);
+        result.push(current);
+      }
+      continue;
+    }
+    if (current.type === COMPOUND) {
+      for (let i = current.arity - 1; i >= 0; i--) stack.push(current.args[i]);
+    }
+  }
+  return result;
+}
+
+function* termAttributedVariablesBuiltin({ goal, env }) {
+  const variables = collectTermVariables(goal.args[0], env).filter((term) => env.hasPrologAttributes(term.name));
+  const next = env.clone();
+  if (unify(goal.args[1], listFromItems(variables), next)) yield next;
+}
+
+function* getAttrListBuiltin({ goal, env }) {
+  const variableTerm = deref(goal.args[0], env);
+  if (variableTerm.type !== VAR) return;
+  const entries = env.prologAttributes(variableTerm.name);
+  if (entries.length === 0) return;
+  const encoded = entries.map(({ module, attribute }) => compound(':', [atom(module), attribute]));
+  const next = env.clone();
+  if (unify(goal.args[1], listFromItems(encoded), next)) yield next;
+}
+
+function* getFromAttrListBuiltin({ goal, env }) {
+  const variableTerm = deref(goal.args[0], env);
+  if (variableTerm.type !== VAR) return;
+  const moduleTerm = deref(goal.args[1], env);
+  if (moduleTerm.type === VAR) throw new PrologError('instantiation_error');
+  if (moduleTerm.type !== ATOM) throw new PrologError('type_error(atom)', moduleTerm);
+  const pattern = deref(goal.args[2], env);
+  if (pattern.type === VAR) throw new PrologError('instantiation_error');
+  const signature = attributeSignature(pattern);
+  if (signature == null) throw new PrologError('type_error(callable)', pattern);
+  const stored = env.getPrologAttribute(variableTerm.name, moduleTerm.name, signature.name, signature.arity);
+  if (stored == null) return;
+  const next = env.clone();
+  if (unify(pattern, stored, next, { skipVariableConstraints: true })) yield next;
+}
+
+function* putToAttrListBuiltin({ goal, env }) {
+  const next = env.clone();
+  const variableTerm = deref(goal.args[0], next);
+  if (variableTerm.type !== VAR) throw new PrologError('uninstantiation_error', variableTerm);
+  const moduleTerm = deref(goal.args[1], next);
+  if (moduleTerm.type === VAR) throw new PrologError('instantiation_error');
+  if (moduleTerm.type !== ATOM) throw new PrologError('type_error(atom)', moduleTerm);
+  const normalized = normalizedAttribute(goal.args[2], next);
+  next.putPrologAttribute(variableTerm.name, moduleTerm.name, normalized.attribute);
+  yield next;
+}
+
+function* delFromAttrListBuiltin({ goal, env }) {
+  const next = env.clone();
+  const variableTerm = deref(goal.args[0], next);
+  if (variableTerm.type !== VAR) { yield next; return; }
+  const moduleTerm = deref(goal.args[1], next);
+  if (moduleTerm.type === VAR) throw new PrologError('instantiation_error');
+  if (moduleTerm.type !== ATOM) throw new PrologError('type_error(atom)', moduleTerm);
+  const normalized = normalizedAttribute(goal.args[2], next);
+  next.deletePrologAttribute(variableTerm.name, moduleTerm.name, normalized.name, normalized.arity);
+  yield next;
+}
+
+export const attsBuiltins = {
+  register(registry) {
+    registry.add('put_atts', 2, putAttsBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('get_atts', 2, getAttsBuiltin, { deterministic: true, eyePrologLibrary: true });
+    // Scryer's CLP(Z) sources use these through goal expansion. EyeProlog
+    // provides them directly so the source does not depend on goal_expansion/2.
+    registry.add('put_attr', 3, putAttrBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('get_attr', 3, getAttrBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('del_attr', 2, delAttrBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('$term_attributed_variables', 2, termAttributedVariablesBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('$get_attr_list', 2, getAttrListBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('$get_from_attr_list', 3, getFromAttrListBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('$put_to_attr_list', 3, putToAttrListBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('$del_from_attr_list', 3, delFromAttrListBuiltin, { deterministic: true, eyePrologLibrary: true });
+  },
+};

package/src/lib/atts.pl

@@ -0,0 +1,20 @@
+/*  Attributed variables compatibility layer.
+
+    The public surface follows Scryer Prolog library(atts). EyeProlog keeps the
+    actual attribute store and verify_attributes/3 scheduling in the generic
+    annotated-variable runtime, so libraries can use put_atts/2 and get_atts/2
+    without code-generation term expansion.
+*/
+
+:- module(atts, [
+    put_atts/2,
+    get_atts/2,
+    put_attr/3,
+    get_attr/3,
+    del_attr/2,
+    term_attributed_variables/2
+]).
+:- op(1199, fx, attribute).
+
+term_attributed_variables(Term, Variables) :-
+    '$term_attributed_variables'(Term, Variables).

package/src/parser.js

@@ -372,9 +372,15 @@ class Parser {
     if (directive.type !== COMPOUND || directive.name !== 'use_module' || ![1, 2].includes(directive.arity)) return;
     const designation = directive.args[0];
     if (designation?.type !== COMPOUND || designation.name !== 'library' || designation.arity !== 1 ||
-        designation.args[0]?.type !== ATOM || designation.args[0].name !== 'clpz') return;
-    for (const [priority, specifier, name] of CLPZ_OPERATOR_DEFINITIONS) {
-      this.defineOperator(priority, specifier, name);
+        designation.args[0]?.type !== ATOM) return;
+    if (designation.args[0].name === 'clpz') {
+      for (const [priority, specifier, name] of CLPZ_OPERATOR_DEFINITIONS) {
+        this.defineOperator(priority, specifier, name);
+      }
+    } else if (designation.args[0].name === 'atts') {
+      // Scryer library(atts) exports this declaration operator. EyeProlog
+      // handles the directive directly instead of relying on term expansion.
+      this.defineOperator(1199, 'fx', 'attribute');
     }
   }
   operatorTokenName(token = this.token) {
@@ -1020,13 +1026,22 @@ class Parser {
       }
       if (this.token.type === TOK.IF) {
         this.advance();
-        const directive = this.parseTerm();
+        const attributeSequence = !this.strictIso && this.operatorTokenName() === 'attribute';
+        let directive = this.parseTerm(0, attributeSequence);
+        // Scryer's library(atts) convention permits declarations such as
+        // `:- attribute a/1, b/0.` without parentheses. At program level the
+        // comma would otherwise sit outside the prefix term; fold it back into
+        // the single attribute/1 directive before directive classification.
+        if (attributeSequence && directive.type === COMPOUND && directive.name === ',' && directive.arity === 2 &&
+            directive.args[0].type === COMPOUND && directive.args[0].name === 'attribute' && directive.args[0].arity === 1) {
+          directive = compound('attribute', [compound(',', [directive.args[0].args[0], directive.args[1]])]);
+        }
         const coreDirective = directive.type === 'compound' && (
           (['dynamic', 'multifile', 'discontiguous', 'initialization', 'include', 'ensure_loaded'].includes(directive.name) && directive.arity === 1) ||
           (['char_conversion', 'set_prolog_flag'].includes(directive.name) && directive.arity === 2)
         );
         const extensionDirective = directive.type === 'compound' && (
-          (['use_module', 'meta_predicate'].includes(directive.name) && directive.arity === 1) ||
+          (['use_module', 'meta_predicate', 'attribute'].includes(directive.name) && directive.arity === 1) ||
           (['module', 'use_module'].includes(directive.name) && directive.arity === 2)
         );
         if (this.strictIso && extensionDirective) {
@@ -1044,7 +1059,7 @@ class Parser {
         // Module loading declarations describe the compilation unit rather
         // than an executable source clause, so they do not shift proof clause
         // numbers in the importing file.
-        if (!['module', 'use_module', 'meta_predicate'].includes(directive.name)) clauseNumber++;
+        if (!['module', 'use_module', 'meta_predicate', 'attribute'].includes(directive.name)) clauseNumber++;
         if (this.sourceMetadata) clause.source = { filename: this.filename, line, clause: clauseNumber };
         accept(clause);
         continue;

package/src/program.js

@@ -1,6 +1,6 @@
 // Program representation and clause indexing.
 // Indexes are deliberately conservative: they speed up common scalar arguments but never replace unification as the final check.
-import { ATOM, COMPOUND, STRING, VAR, Env, atom, compound, deref, flattenConjunction, isScalar, numberTerm, properListItems, termToString, variable } from './term.js';
+import { ATOM, COMPOUND, NUMBER, STRING, VAR, Env, atom, compound, deref, flattenConjunction, isScalar, numberTerm, properListItems, termToString, variable } from './term.js';
 import { formatTermForWrite } from './write.js';
 import {
   ISO_OPERATOR_DEFINITIONS,
@@ -1195,6 +1195,19 @@ function moduleExportIndicators(term) {
   if (items == null) return null;
   const indicators = [];
   for (const item of items) {
+    // Scryer-style modules may export operators alongside predicate
+    // indicators, for example op(700, xfx, #=) from library(clpz).
+    // Operator visibility while parsing bundled libraries is handled by the
+    // parser's imported-library operator table; module import resolution only
+    // needs procedure indicators here.
+    if (item.type === COMPOUND && item.name === 'op' && item.arity === 3) {
+      const [priority, specifier, names] = item.args;
+      const operatorNames = names.type === ATOM ? [names] : properListItems(names, new Env());
+      if (priority.type !== NUMBER || !/^\d+$/.test(priority.name) || Number(priority.name) > 1200 ||
+          specifier.type !== ATOM || !['fx', 'fy', 'xf', 'yf', 'xfx', 'xfy', 'yfx'].includes(specifier.name) ||
+          operatorNames == null || operatorNames.some((name) => name.type !== ATOM)) return null;
+      continue;
+    }
     if (item.type !== COMPOUND || !['/', '//'].includes(item.name) || item.arity !== 2) return null;
     const indicator = predicateIndicator(item.args[0], item.args[1]);
     if (!indicator) return null;

package/src/repl.js

@@ -753,6 +753,24 @@ function formatAnswer(engine, state, variables, env) {
       doubleQuotes: state.solver.prologFlags.get('double_quotes')?.value?.name ?? 'chars',
     }));
   }
+  const projectedAttributeRoots = new Set();
+  for (const variable of variables) {
+    const root = engine.deref(variable, env);
+    if (root.type !== 'var' || projectedAttributeRoots.has(root.name) || !env.hasPrologAttributes?.(root.name)) continue;
+    projectedAttributeRoots.add(root.name);
+    names.set(root.name, variable.name);
+    for (const residual of state.solver.attributeResidualGoals(root, env)) {
+      collectUnboundVariables(engine, residual, env, names, () => `_${letterName(generated++)}`);
+      bindings.push(engine.formatTermForWrite(residual, env, {
+        quoted: true,
+        operators,
+        variableNames: names,
+        operatorAtomsAsArgs: true,
+        dottedGraphicAtoms: true,
+        doubleQuotes: state.solver.prologFlags.get('double_quotes')?.value?.name ?? 'chars',
+      }));
+    }
+  }
   return bindings.length === 0 ? 'true' : bindings.join(', ');
 }
 

package/src/solver.js

@@ -3,7 +3,7 @@
 import {
   ATOM, COMPOUND, NUMBER, STRING, VAR, Env, compactListLength, compactVariableList, compound, cons, copyResolved, deref, emptyList,
   flattenConjunction, freshTerm, isCons, isDecimalInteger, isEmptyList,
-  numberTerm, numberTextFromDouble, termIsGround, termToString, unify, variable, variantTerms,
+  numberTerm, numberTextFromDouble, properListItems, termIsGround, termToString, unify, variable, variantTerms,
 } from './term.js';
 import { numberValueKey, sameNumberValue } from './number-value.js';
 import { PrologError, getStrictIsoRegistry } from './iso.js';
@@ -32,6 +32,23 @@ function qualifyTerm(term, module) {
   return term;
 }
 
+function renameVariableInTerm(term, fromName, toName) {
+  if (fromName === toName) return term;
+  const stack = [term];
+  const seen = new Set();
+  while (stack.length) {
+    const current = stack.pop();
+    if (current == null || seen.has(current)) continue;
+    seen.add(current);
+    if (current.type === VAR) {
+      if (current.name === fromName) current.name = toName;
+      continue;
+    }
+    if (current.type === COMPOUND) for (const arg of current.args) stack.push(arg);
+  }
+  return term;
+}
+
 export function nextFreshId() {
   return ++freshCounter;
 }
@@ -120,6 +137,8 @@ export class Solver {
         raiseOccursCheckError(left, right, env);
       }
     };
+    this.attributeHookRunner = (module, attributed, other, env) =>
+      this.runAttributeHook(module, attributed, other, env);
     this.charConversions = options.charConversions ?? new Map();
     if (!options.prologFlags) {
       if (['chars', 'codes', 'atom'].includes(program.doubleQuotes)) {
@@ -303,6 +322,54 @@ export class Solver {
     }
   }
 
+  runAttributeHook(module, attributed, other, env) {
+    if (this.program.findGroup('verify_attributes', 3, module) == null) return true;
+    const goalsVariable = variable(`\u0000attributeGoals${nextFreshId()}`);
+    const hook = compound('verify_attributes', [attributed, other, goalsVariable]);
+    qualifyTerm(hook, module);
+    const child = this.cloneForInnerGoal(1);
+    const iterator = child.solve([hook], env.clone(), 0);
+    const result = iterator.next();
+    try { iterator.return?.(); } catch (_) { /* best-effort iterator cleanup */ }
+    this.absorbStatsFrom(child);
+    if (result.done) return false;
+    env.adopt(result.value);
+    env.setOccursCheckHandler(this.occursCheckHandler);
+    env.setAttributeHookRunner(this.attributeHookRunner);
+    const goals = properListItems(goalsVariable, env);
+    if (goals == null) throw new PrologError('type_error(list)', deref(goalsVariable, env));
+    for (const goal of goals) qualifyTerm(goal, module);
+    env.enqueueAttributeGoals(goals);
+    return true;
+  }
+
+  attributeResidualGoals(variableTerm, env) {
+    const root = deref(variableTerm, env);
+    if (root.type !== VAR || !env.hasPrologAttributes(root.name)) return [];
+    const residuals = [];
+    for (const module of env.prologAttributeModules(root.name)) {
+      if (this.program.findGroup('attribute_goals', 3, module) == null) continue;
+      const goalsVariable = variable(`\u0000attributeResidual${nextFreshId()}`);
+      const projection = compound('attribute_goals', [root, goalsVariable, emptyList()]);
+      qualifyTerm(projection, module);
+      const child = this.cloneForInnerGoal(1);
+      const iterator = child.solve([projection], env.clone(), 0);
+      const result = iterator.next();
+      try { iterator.return?.(); } catch (_) { /* best-effort iterator cleanup */ }
+      this.absorbStatsFrom(child);
+      if (result.done) continue;
+      const goals = properListItems(goalsVariable, result.value);
+      if (goals == null) throw new PrologError('type_error(list)', deref(goalsVariable, result.value));
+      const projectedRoot = deref(root, result.value);
+      for (const goal of goals) {
+        const residual = copyResolved(goal, result.value);
+        if (projectedRoot.type === VAR) renameVariableInTerm(residual, projectedRoot.name, root.name);
+        residuals.push(residual);
+      }
+    }
+    return residuals;
+  }
+
   runInitializations() {
     if (this.program._initializationsExecuted) return;
     for (const goal of this.program.initializations ?? []) {
@@ -321,6 +388,7 @@ export class Solver {
   *solve(goals, env = new Env(), depth = 0) {
     if (!Array.isArray(goals)) goals = [goals];
     env.setOccursCheckHandler(this.occursCheckHandler);
+    env.setAttributeHookRunner(this.attributeHookRunner);
     if (this.isoStrict) rejectStrictIsoStringTerms(goals, env);
 
     const writeVariableState = this.writeVariableState;
@@ -386,6 +454,7 @@ export class Solver {
       goals = frame.goals;
       env = frame.env;
       env.setOccursCheckHandler(this.occursCheckHandler);
+      env.setAttributeHookRunner(this.attributeHookRunner);
       depth = frame.depth;
       let active = frame.active;
 
@@ -408,6 +477,9 @@ export class Solver {
         }
         if (this.solutionsSeen >= this.solutionLimit) break;
 
+        const pendingAttributeGoals = env.takePendingAttributeGoals?.() ?? [];
+        if (pendingAttributeGoals.length > 0) goals = [...pendingAttributeGoals, ...goals];
+
         const readyDelays = env.takeReadyDelays();
         if (readyDelays.length > 0) {
           const awakened = readyDelays.map(({ goal, module }) => {
@@ -1971,7 +2043,7 @@ function fastCountBranch(branch, env) {
 
 function fastCountPureGoal(solver, goal, env) {
   if (solver.isoStrict || solver.solutionLimit !== Infinity || solver.maxInferences !== Infinity ||
-      env._clpz != null || env._variableConstraints != null || (env._delays != null && env._delays.size !== 0)) return null;
+      env._clpz != null || env._variableConstraints != null || env._prologAttributes != null || (env._delays != null && env._delays.size !== 0)) return null;
   const budget = { remaining: 8192 };
   const branches = expandPureCountGoal(solver, goal, goal.module ?? 'user', new Set(), budget);
   if (branches == null) return null;
@@ -1981,6 +2053,7 @@ function fastCountPureGoal(solver, goal, env) {
 }
 
 function tryPushScalarFactRunFrames(stack, solver, goals, env, depth, active) {
+  if (env._prologAttributes != null) return false;
   // Consecutive scalar-fact lookups are common in data-heavy joins.  Short
   // joins are fastest when their continuation frames are materialized locally;
   // wide joins can explode combinatorially, so they are streamed lazily.
@@ -2164,6 +2237,11 @@ function matchScalarFactLocal(goal, head, env, names, values) {
 }
 
 function matchScalarFact(goal, head, env) {
+  if (env._prologAttributes != null) {
+    const next = env.clone();
+    if (!unify(goal, head, next)) return null;
+    return next;
+  }
   // A scalar ground fact has no variables to freshen and no compound structure
   // to traverse. Match the goal arguments directly and clone only after the
   // candidate has succeeded.

package/src/standard-library.js

@@ -4,12 +4,14 @@
 // source-level interop autoloader declared below.
 import { PrologError, createDefaultRegistry, eyePrologLibraryBuiltins } from './iso.js';
 import { clpzBuiltins } from './clpz.js';
+import { attsBuiltins } from './atts.js';
 import { registerCleanupBuiltins } from './cleanup.js';
 import { fs, isNode, memoryStatistics } from './platform.js';
 import { ATOM, VAR, atom, deref, numberTerm, unify } from './term.js';
 
 const moduleFiles = Object.freeze({
   aggregate: 'aggregate.pl',
+  atts: 'atts.pl',
   clpz: 'clpz.pl',
   comparison: 'comparison.pl',
   dates: 'dates.pl',
@@ -49,6 +51,7 @@ function libraryUrl(filename) {
 
 export const eyePrologNativeLibraryIndicators = Object.freeze([
   'call_nth/2', 'freeze/2', 'dif/2', 'countall/2', 'time/1',
+  'put_atts/2', 'get_atts/2', 'put_attr/3', 'get_attr/3', 'del_attr/2', 'term_attributed_variables/2',
   '#>/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',
@@ -137,7 +140,7 @@ export const eyePrologInteropLibraryIndicators = Object.freeze(
 // Libraries whose *name* is part of the current interop profile.  A program
 // may freely use_module/1 with these common module names; predicates in those
 // modules outside eyePrologInteropLibraryIndicators are still diagnosed when used.
-export const eyePrologInteropLibraryModules = Object.freeze(['lists', 'iso_ext', 'lambda']);
+export const eyePrologInteropLibraryModules = Object.freeze(['lists', 'iso_ext', 'lambda', 'atts']);
 
 function* tabledNegationBuiltin({ solver, goal, env }) {
   yield* solver.solveTabledNegation(goal.args[0], env);
@@ -184,6 +187,7 @@ export function createEyePrologRegistry() {
   registry.add('tnot', 1, tabledNegationBuiltin, { deterministic: true });
   registerCleanupBuiltins(registry);
   eyePrologLibraryBuiltins.register(registry);
+  attsBuiltins.register(registry);
   clpzBuiltins.register(registry);
   registry.eyePrologLibrary = true;
   return registry;

package/src/term.js

@@ -102,6 +102,13 @@ export class Env {
     // is copied only when a branch adds, removes, or reindexes a constraint.
     this._variableConstraints = null;
     this._variableAnnotations = null;
+    // Prolog-visible attributed variables. The outer map is indexed by the
+    // current unbound representative name; each representative owns module-
+    // scoped attribute terms keyed by functor/arity. Maps are copy-on-write so
+    // Env.clone() keeps ordinary Prolog backtracking constant-time.
+    this._prologAttributes = null;
+    this._attributeHookRunner = null;
+    this._pendingAttributeGoals = null;
     this._clpz = null;
     this._occursCheckHandler = null;
     this._localVariables = null;
@@ -117,6 +124,9 @@ export class Env {
     clone._delays = this._delays;
     clone._variableConstraints = this._variableConstraints;
     clone._variableAnnotations = this._variableAnnotations;
+    clone._prologAttributes = this._prologAttributes;
+    clone._attributeHookRunner = this._attributeHookRunner;
+    clone._pendingAttributeGoals = this._pendingAttributeGoals;
     clone._clpz = this._clpz;
     clone._occursCheckHandler = this._occursCheckHandler;
     clone._localVariables = this._localVariables;
@@ -126,6 +136,24 @@ export class Env {
     this._occursCheckHandler = typeof handler === 'function' ? handler : null;
     return this;
   }
+  setAttributeHookRunner(handler) {
+    this._attributeHookRunner = typeof handler === 'function' ? handler : null;
+    return this;
+  }
+  adopt(other) {
+    if (!(other instanceof Env)) throw new TypeError('Env.adopt expects Env');
+    this._state = other._state;
+    this._delays = other._delays;
+    this._variableConstraints = other._variableConstraints;
+    this._variableAnnotations = other._variableAnnotations;
+    this._prologAttributes = other._prologAttributes;
+    this._pendingAttributeGoals = other._pendingAttributeGoals;
+    this._clpz = other._clpz;
+    // Execution callbacks belong to the Solver driving this Env, not to the
+    // logical branch being adopted from an inner attribute-hook call.
+    this._localVariables = other._localVariables;
+    return this;
+  }
   hasLocalVariables() {
     return this._localVariables != null && this._localVariables.size !== 0;
   }
@@ -243,6 +271,150 @@ export class Env {
     if (ready.length > 0) this._delays = remaining;
     return ready;
   }
+  _attributeRootName(name) {
+    const root = deref(variable(name), this);
+    return root.type === VAR ? root.name : null;
+  }
+  _attributeModulesForRoot(name) {
+    const root = this._attributeRootName(name);
+    return root == null ? null : (this._prologAttributes?.get(root) ?? null);
+  }
+  prologAttributes(name, module = null) {
+    const modules = this._attributeModulesForRoot(name);
+    if (modules == null) return [];
+    if (module != null) return [...(modules.get(module)?.values() ?? [])];
+    const result = [];
+    for (const [owner, attrs] of modules) {
+      for (const attribute of attrs.values()) result.push({ module: owner, attribute });
+    }
+    return result;
+  }
+  prologAttributeModules(name) {
+    const modules = this._attributeModulesForRoot(name);
+    return modules == null ? [] : [...modules.keys()];
+  }
+  getPrologAttribute(name, module, functor, arity) {
+    const modules = this._attributeModulesForRoot(name);
+    return modules?.get(module)?.get(`${functor}/${arity}`) ?? null;
+  }
+  putPrologAttribute(name, module, attribute) {
+    const root = this._attributeRootName(name);
+    if (root == null) return false;
+    const signature = `${attribute.name}/${attribute.arity}`;
+    const outer = new Map(this._prologAttributes ?? []);
+    const modules = new Map(outer.get(root) ?? []);
+    const attrs = new Map(modules.get(module) ?? []);
+    attrs.set(signature, attribute);
+    modules.set(module, attrs);
+    outer.set(root, modules);
+    this._prologAttributes = outer;
+    return true;
+  }
+  deletePrologAttribute(name, module, functor, arity = null) {
+    const root = this._attributeRootName(name);
+    if (root == null) return false;
+    const existingModules = this._prologAttributes?.get(root);
+    const existingAttrs = existingModules?.get(module);
+    if (existingAttrs == null) return false;
+    const attrs = new Map(existingAttrs);
+    let deleted = false;
+    if (arity == null) {
+      for (const key of [...attrs.keys()]) {
+        if (key.startsWith(`${functor}/`)) { attrs.delete(key); deleted = true; }
+      }
+    } else {
+      deleted = attrs.delete(`${functor}/${arity}`);
+    }
+    if (!deleted) return false;
+    const modules = new Map(existingModules);
+    if (attrs.size === 0) modules.delete(module); else modules.set(module, attrs);
+    const outer = new Map(this._prologAttributes);
+    if (modules.size === 0) outer.delete(root); else outer.set(root, modules);
+    this._prologAttributes = outer.size === 0 ? null : outer;
+    return true;
+  }
+  hasPrologAttributes(name) {
+    const modules = this._attributeModulesForRoot(name);
+    if (modules == null) return false;
+    for (const attrs of modules.values()) if (attrs.size !== 0) return true;
+    return false;
+  }
+  attributedVariableNames() {
+    if (this._prologAttributes == null) return [];
+    const names = [];
+    const seen = new Set();
+    for (const name of this._prologAttributes.keys()) {
+      const root = deref(variable(name), this);
+      if (root.type !== VAR || seen.has(root.name)) continue;
+      if (!this.hasPrologAttributes(root.name)) continue;
+      seen.add(root.name);
+      names.push(root.name);
+    }
+    return names;
+  }
+  enqueueAttributeGoals(goals) {
+    if (goals == null || goals.length === 0) return;
+    this._pendingAttributeGoals = [...(this._pendingAttributeGoals ?? []), ...goals];
+  }
+  takePendingAttributeGoals() {
+    if (this._pendingAttributeGoals == null || this._pendingAttributeGoals.length === 0) return [];
+    const goals = this._pendingAttributeGoals;
+    this._pendingAttributeGoals = null;
+    return goals;
+  }
+  _ownerModules(name) {
+    const modules = this._attributeModulesForRoot(name);
+    return modules == null ? [] : [...modules.keys()];
+  }
+  _targetHasOwnerModule(name, module) {
+    return this._attributeModulesForRoot(name)?.has(module) === true;
+  }
+  preparePrologAttributeUnification(variableTerm, otherTerm) {
+    if (this._prologAttributes == null || variableTerm?.type !== VAR) return true;
+    const sourceRoot = deref(variableTerm, this);
+    if (sourceRoot.type !== VAR) return true;
+    const modules = this._ownerModules(sourceRoot.name);
+    if (modules.length === 0) return true;
+    const other = deref(otherTerm, this);
+    if (other.type === VAR) {
+      if (other.name === sourceRoot.name) return true;
+      // Aliasing an attributed variable with a plain variable is just a
+      // representative change. No user-level hook is needed; final aliasing
+      // moves the attributes to the surviving representative.
+      const hooks = modules.filter((module) => this._targetHasOwnerModule(other.name, module));
+      for (const module of hooks) {
+        if (this._attributeHookRunner && !this._attributeHookRunner(module, sourceRoot, other, this)) return false;
+      }
+      return true;
+    }
+    for (const module of modules) {
+      if (this._attributeHookRunner && !this._attributeHookRunner(module, sourceRoot, other, this)) return false;
+    }
+    return true;
+  }
+  finalizePrologAttributeAlias(sourceName, targetName) {
+    if (this._prologAttributes == null || sourceName === targetName) return;
+    const source = this._prologAttributes.get(sourceName);
+    if (source == null) return;
+    const outer = new Map(this._prologAttributes);
+    const target = new Map(outer.get(targetName) ?? []);
+    for (const [module, sourceAttrs] of source) {
+      const attrs = new Map(target.get(module) ?? []);
+      for (const [signature, attribute] of sourceAttrs) {
+        if (!attrs.has(signature)) attrs.set(signature, attribute);
+      }
+      target.set(module, attrs);
+    }
+    outer.delete(sourceName);
+    outer.set(targetName, target);
+    this._prologAttributes = outer;
+  }
+  dropPrologAttributes(name) {
+    if (this._prologAttributes == null) return;
+    const outer = new Map(this._prologAttributes);
+    outer.delete(name);
+    this._prologAttributes = outer.size === 0 ? null : outer;
+  }
   addVariableConstraint(constraint) {
     if (constraint == null || typeof constraint.variables !== 'function' ||
         typeof constraint.status !== 'function') {
@@ -374,6 +546,15 @@ export function unify(left, right, env, options = {}) {
 
     if (a.type === VAR && b.type === VAR && a.name === b.name) continue;
     if (a.type === VAR && b.type === VAR) {
+      if (env?._prologAttributes != null) {
+        if (!env.preparePrologAttributeUnification(a, b)) return false;
+        a = deref(a, env);
+        b = deref(b, env);
+        if (a.type !== VAR || b.type !== VAR || a.name === b.name) {
+          stack.push([a, b]);
+          continue;
+        }
+      }
       // For a compiler-generated DCG state handed directly to another
       // nonterminal, keep the local caller variable as representative. Ordinary
       // aliases retain the established direction and observable conventions.
@@ -381,9 +562,11 @@ export function unify(left, right, env, options = {}) {
         a.name.startsWith('\u0000dcg') && b.name.startsWith('\u0000dcg');
       if (aLocalDcg) {
         markCompactVariableBound(b);
+        env?.finalizePrologAttributeAlias?.(b.name, a.name);
         env.bind(b.name, a);
       } else {
         markCompactVariableBound(a);
+        env?.finalizePrologAttributeAlias?.(a.name, b.name);
         env.bind(a.name, b);
       }
       continue;
@@ -394,7 +577,14 @@ export function unify(left, right, env, options = {}) {
         occursCheckHandler?.(a, b, env);
         return false;
       }
+      if (env?._prologAttributes != null && env.hasPrologAttributes(a.name)) {
+        if (!env.preparePrologAttributeUnification(a, b)) return false;
+        a = deref(a, env);
+        b = deref(b, env);
+        if (a.type !== VAR) { stack.push([a, b]); continue; }
+      }
       markCompactVariableBound(a);
+      env?.dropPrologAttributes?.(a.name);
       env.bind(a.name, b);
       if (aLocal) env.forgetLocalVariable(a.name);
       continue;
@@ -405,7 +595,14 @@ export function unify(left, right, env, options = {}) {
         occursCheckHandler?.(b, a, env);
         return false;
       }
+      if (env?._prologAttributes != null && env.hasPrologAttributes(b.name)) {
+        if (!env.preparePrologAttributeUnification(b, a)) return false;
+        b = deref(b, env);
+        a = deref(a, env);
+        if (b.type !== VAR) { stack.push([a, b]); continue; }
+      }
       markCompactVariableBound(b);
+      env?.dropPrologAttributes?.(b.name);
       env.bind(b.name, a);
       if (bLocal) env.forgetLocalVariable(b.name);
       continue;

package/test/run-regression.mjs

@@ -129,6 +129,62 @@ function regressionCases() {
           'scalar-fact fast matching can discharge an annotated disequality');
       },
     },
+    {
+      name: 'library(atts) provides Scryer-style attributed-variable hooks',
+      run: () => {
+        const source = `:- module(attr_probe, [check_get/0, check_alias/0, check_ok/0, check_bad/0, check_conflict/0, check_backtrack/0, check_term_vars/0]).
+:- use_module(library(atts)).
+:- attribute mark/1.
+attach(X, V) :- put_atts(X, mark(V)).
+verify_attributes(Var, Other, Goals) :-
+    ( get_atts(Var, mark(V)) ->
+        ( var(Other) ->
+            ( get_atts(Other, mark(W)) -> V = W ; put_atts(Other, mark(V)) ),
+            Goals = []
+        ; Goals = [same(Other, V)] )
+    ; Goals = [] ).
+same(X, Y) :- X = Y.
+check_get :- attach(X, a), get_atts(X, mark(a)), X = a.
+check_alias :- attach(X, a), X = Y, get_atts(Y, mark(a)), Y = a.
+check_ok :- attach(X, 3), X = 3.
+check_bad :- attach(X, 3), X = 4.
+check_conflict :- attach(X, a), attach(Y, b), X = Y.
+check_backtrack :- (attach(X, a), fail ; true), \\+ get_atts(X, mark(_)).
+check_term_vars :- attach(X, a), term_attributed_variables(pair(X,Y), [X]), var(Y), X = a.
+`;
+        assertIncludes(run(source, { goal: 'attr_probe:check_get' }).stdout, 'attr_probe:check_get.', 'get_atts/2');
+        assertIncludes(run(source, { goal: 'attr_probe:check_alias' }).stdout, 'attr_probe:check_alias.', 'attribute transfer on aliasing');
+        assertIncludes(run(source, { goal: 'attr_probe:check_ok' }).stdout, 'attr_probe:check_ok.', 'post-binding hook goals');
+        assertEqual(run(source, { goal: 'attr_probe:check_bad' }).stdout, '', 'post-binding hook can reject a binding');
+        assertEqual(run(source, { goal: 'attr_probe:check_conflict' }).stdout, '', 'same-module attributes are verified before aliasing');
+        assertIncludes(run(source, { goal: 'attr_probe:check_backtrack' }).stdout, 'attr_probe:check_backtrack.', 'attributes backtrack with Env branches');
+        assertIncludes(run(source, { goal: 'attr_probe:check_term_vars' }).stdout, 'attr_probe:check_term_vars.', 'term_attributed_variables/2');
+
+        const residualFile = path.join(tmp, `atts-residual-${++tmpCounter}.pl`);
+        fs.writeFileSync(residualFile, `:- use_module(library(atts)).
+:- attribute required/1.
+attach(X,V) :- put_atts(X, required(V)).
+verify_attributes(Var, Other, Goals) :-
+    ( get_atts(Var, required(V)) ->
+        ( var(Other) -> put_atts(Other, required(V)), Goals=[] ; Goals=[same(Other,V)] )
+    ; Goals=[] ).
+same(X,X).
+attribute_goals(X) --> { get_atts(X, required(V)) }, [required(X,V)].
+`);
+        const repl = runCli([], { input: `[${sourceAtom(residualFile)}].\nattach(X,a).\nhalt.\n` });
+        assertEqual(repl.status, 0, 'attribute residual REPL status');
+        assertIncludes(repl.stdout, 'required(X, a).', 'attribute_goals//1 residual projection');
+
+        const scryerShape = Program.parse(`:- module(scryer_shape, [op(700, xfx, #=), probe/0]).
+:- op(700, xfx, #=).
+:- use_module(library(atts)).
+:- attribute first/1, second/0.
+probe.
+`);
+        assertEqual(scryerShape.findGroup('probe', 0, 'scryer_shape')?.module, 'scryer_shape',
+          'Scryer-style operator exports and multi-attribute directives load');
+      },
+    },
     {
       name: 'write_term variable_names/1 errors preserve the instantiated option culprit (issue #69)',
       run: () => {
@@ -3626,8 +3682,8 @@ 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/standard-library.js',
-          'src/lib/aggregate.pl', 'src/lib/comparison.pl', 'src/lib/dates.pl',
+        for (const filename of ['src/iso.js', 'src/dcg.js', 'src/atts.js', 'src/standard-library.js',
+          'src/CLPZ-MIGRATION.md', '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']) {
@@ -4729,7 +4785,7 @@ answer(ok) :-
         assertEqual(Boolean(registry.get('is', 2)), true, 'ISO is/2 exists');
         assertEqual(Boolean(registry.get('append', 3)), false, 'append/3 is not ISO core');
         assertEqual(library.eyePrologLibrary, true, 'complete registry marker');
-        assertEqual(library.defs.size, 161, 'EyeProlog registry contains ISO definitions, cleanup controls, observability extensions, WFS tnot/1, and private library adapters');
+        assertEqual(library.defs.size, 171, 'EyeProlog registry contains ISO definitions, cleanup controls, observability extensions, WFS tnot/1, and private library adapters');
         assertEqual(Boolean(registry.get('phrase', 2)), true, 'Part 3 phrase/2 exists');
         assertEqual(Boolean(registry.get('phrase', 3)), true, 'Part 3 phrase/3 exists');
         assertEqual(registry.get('statistics', 0), null, 'statistics/0 is absent from the ISO registry');
@@ -4746,19 +4802,19 @@ 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, 42, 'public native EyeProlog builtin count');
+        assertEqual(registeredNativeEyePrologLibraryNames().length, 48, 'public native EyeProlog builtin count');
         assertEqual(eyePrologPortableLibraryIndicators.length, 87, 'portable Prolog library count');
         assertEqual(eyePrologInteropLibraryIndicators.length, 29, 'cross-implementation interop profile count');
-        assertEqual(eyePrologInteropLibraryModules.join(','), 'lists,iso_ext,lambda', 'common explicit library module profile');
+        assertEqual(eyePrologInteropLibraryModules.join(','), 'lists,iso_ext,lambda,atts', 'common explicit library module profile');
         assertEqual(eyePrologInteropAutoload['member/2'], 'lists', 'member/2 canonical autoload');
         assertEqual(eyePrologInteropAutoload['between/3'], 'prologue', 'between/3 canonical internal autoload');
         assertEqual(eyePrologInteropAutoload['call_nth/2'], 'iso_ext', 'call_nth/2 canonical interop autoload');
         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, 42, 'native host library count');
+        assertEqual(eyePrologNativeLibraryIndicators.length, 48, 'native host 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, 129, 'complete EyeProlog library surface');
+        assertEqual(eyePrologLibraryIndicators.length, 135, 'complete 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(library.get('eyeprolog__call_nth', 2)?.eyePrologLibrary, true, 'private adapter is marked as library support');
@@ -4769,6 +4825,9 @@ answer(ok) :-
         assertEqual(Boolean(library.get('eyeprolog__time', 1)), true, 'private time adapter is registered for EyeProlog');
         assertEqual(Boolean(library.get('eyeprolog__clpz_labeling', 2)), true, 'private CLP(Z) labeling adapter is registered');
         assertEqual(Boolean(library.get('eyeprolog__clpz_global_cardinality', 3)), true, 'private CLP(Z) cardinality adapter is registered');
+        assertEqual(registry.get('put_atts', 2), null, 'put_atts/2 is absent from the ISO registry');
+        assertEqual(Boolean(library.get('put_atts', 2)), true, 'put_atts/2 is registered for attributed-variable libraries');
+        assertEqual(Boolean(library.get('$put_to_attr_list', 3)), true, 'private attribute-list adapter is registered');
         assertEqual(library.get('between', 3), null, 'between/3 remains portable Prolog');
         assertEqual(library.get('smallest_divisor_from', 3), null, 'smallest_divisor_from/3 remains portable Prolog');
         assertEqual(library.get('random', 3), null, 'random/3 remains portable Prolog');

package/the-art-of-eyeprolog.md

@@ -6211,18 +6211,18 @@ so side effects occur in Prolog execution order.
 
 ### The EyeProlog library
 
-EyeProlog exposes **129 library predicate indicators** in addition to the 129
-indicators in its isolated ISO profile. **88 are defined entirely as ordinary
+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
-**258 public predicate indicators**. Most library relations remain module source
+**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.
 
-The sources are `src/lib/aggregate.pl`, `src/lib/clpz.pl`, `src/lib/comparison.pl`,
+The sources are `src/lib/aggregate.pl`, `src/lib/atts.pl`, `src/lib/clpz.pl`, `src/lib/comparison.pl`,
 `src/lib/dates.pl`, `src/lib/iso_ext.pl`, `src/lib/lambda.pl`,
 `src/lib/lists.pl`, `src/lib/primes.pl`, `src/lib/prologue.pl`,
 `src/lib/random.pl`, `src/lib/strings.pl`, and `src/lib/uuid.pl`. Each declares a same-named module
@@ -6253,6 +6253,7 @@ between solution branches.
 | 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` |
 | `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` |
@@ -6402,17 +6403,32 @@ The catalog above is authoritative for the complete EyeProlog library surface.
 The following notes describe useful parts of that surface without extending the
 cross-engine claims made above.
 
+`library(atts)` is the Prolog-facing attributed-variable layer over the persistent
+annotated-variable machinery in `src/term.js`, with its small host bridge in
+`src/atts.js`. It provides the attribute operations used by Scryer libraries,
+accepts `:- attribute ...` declarations, invokes module-local
+`verify_attributes/3` before an attributed binding is committed, and schedules
+the returned goals immediately after the binding. Attribute maps are copied only
+when changed and therefore backtrack with `Env` branches; the interactive top
+level projects module `attribute_goals//1` hooks as residual goals. The checked
+[`examples/attributed-variables.pl`](https://github.com/eyereasoner/eyeprolog/blob/main/examples/attributed-variables.pl)
+demonstrates binding verification and attribute transfer across aliases.
+
 `library(clpz)` follows the familiar Trealla and Scryer convention for
 constraint logic programming over integers. EyeProlog currently provides finite
 interval and union domains, arithmetic and reified constraints, backtrackable
 labeling with `ff`, `up`, and `down`, global distinctness, linear sums and scalar
 products, chains, elements, value counting, extensional tuple tables,
 lexicographic chains, serialized schedules, global cardinality with costs,
-Hamiltonian circuits, three-way comparison, and domain reflection. Constraints
-are kept in the logical environment, so failed alternatives cannot leak domains
-into later branches. Trealla's larger library also contains facilities such as
-automata, cumulative and two-dimensional scheduling constraints, and
-unbounded-domain propagation that EyeProlog does not currently export.
+Hamiltonian circuits, three-way comparison, and domain reflection. Its existing
+`src/clpz.js` store is now explicitly transitional: the attributed-variable layer
+is intended to support staged reuse of Markus Triska's MIT-licensed
+[Scryer `clpz.pl`](https://github.com/mthom/scryer-prolog/blob/master/src/lib/clpz.pl).
+The remaining blockers are compile-time term/goal expansion and the supporting
+library surface used by that source; the migration state is tracked in
+[`src/CLPZ-MIGRATION.md`](src/CLPZ-MIGRATION.md). Until parity is reached, the JS
+kernel remains the active implementation so existing CLP(Z) behavior does not
+regress.
 
 Alongside its interop entries `call_nth/2`, `time/1`, and `.../2`,
 `library(iso_ext)` also exports EyeProlog's extension relations `countall/2`,
@@ -7131,7 +7147,7 @@ Review questions:
 </figure>
 
 The [examples directory](https://github.com/eyereasoner/eyeprolog/tree/main/examples/) is the book's executable companion. The
-top-level directory contains **212 self-contained runnable programs**. Every
+top-level directory contains **213 self-contained runnable programs**. Every
 source program has an exact answer file under
 [examples/output](https://github.com/eyereasoner/eyeprolog/tree/main/examples/output/), and **61 selected programs** have a checked
 explanation under [examples/proof](https://github.com/eyereasoner/eyeprolog/tree/main/examples/proof/). The thematic tables below link every top-level program and open the program