🧠 Logic: ♻️ Refactor prolog predicates errors

[ccamel]

Background

As of now, the error messages generated by our predicates in the logic module lack standardization. They are generated in a relatively free text format, although prefixed with the name of the faulty functor.

Example:
For instance, consider the error message from the bech32_address/2 predicate:

"bech32_address/2: failed to convert term to bytes list: invalid term type in list at position 1: engine.Atom, only engine.Integer allowed"

This message does not conform to a standardized format. It describes the nature of the error (failure to convert a term to a bytes list) and identifies the specific issue (invalid term type), but it does so in a textual format.

Proposal

The proposal is to transition from text-described errors to errors represented by Prolog terms. These terms must be highly compatible with the conventions outlined in SWI-Prolog's documentation. This foundation for the approach exists in Itchiban Prolog.

Example:

Applying this format to the aforementioned example from bech32_address/2, the error message would be transformed into:

error(domain_error(valid_character_code(8956), [8956, 167, 23, 244, 162, 175, 49, 162, 170, 15, 181, 141, 68, 134, 141, 168, 18, 56, 247, 30]), bech32_address/2)

error and domain_error/2 are quite standard prolog terms.

Motivation

What we're looking for through this change is fairly common:

• consistency: Utilizing a standardized format ensures uniformity across all predicates.
• clarity: The standardized format offers a clear and predictable structure for error messages, enhancing their understandability and ease of debugging.
• interoperability: Standardization improves interoperability with systems that use the logic module, particularly as errors are now expressed in Prolog language.
• ease of learning: This standardization potentially reduces the learning curve for new users, especially those familiar with SWI-Prolog or its documentation, due to the presence of familiar elements.

Impact

This modification results in a breaking change as it alters the established contract of most predicates, particularly those that can fail.

Todo

• Standardize all custom predicates (under x/logic/predicate. Add additional terms to describe certain error classes if necessary (e.g. valid_byte atom represents the condition of a valid 0-255 interger).
• Update the tests accordingly.