eyeprolog 1.3.66 → 1.3.68

package/README.md

@@ -147,6 +147,28 @@ 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).
+
+The second migration stage toward reusing Markus Triska's MIT-licensed
+[Scryer `library(clpz)`](https://github.com/mthom/scryer-prolog/blob/master/src/lib/clpz.pl)
+is now in place as well. Normal-profile loading supports user-defined
+`term_expansion/2` and `goal_expansion/2`, clause-list generation, and
+`expand_term/2` for processor DCG lowering, including the qualified hook shape
+used by Scryer libraries. The current CLP(Z) implementation remains active while
+the remaining Scryer support-library surface is brought across. 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 +297,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.68",
   "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

@@ -7,15 +7,15 @@ higher-level frontends.
 
 1. **Kernel representation and syntax** — `term.js`, `number-value.js`,
    `syntax-scan.js`, `parser.js`, `write.js`, `errors.js`.
-2. **Program preparation** — `program.js` plus `program-analysis.js` and
-   `program-indexing.js`. Static recursion/Datalog/WFS classification lives in
+2. **Program preparation** — `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`.
 3. **Execution** — `solver.js`, `cleanup.js`, `io.js`, `datalog.js`, `wfs.js`,
    `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,27 @@ 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`.
+
+`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/`; the existing `src/lib/`
 contains Prolog library sources rather than JavaScript runtime modules. The architecture

package/src/CLPZ-MIGRATION.md

@@ -0,0 +1,81 @@
+# 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.
+
+## Stage 2: source expansion substrate
+
+This stage is implemented. Normal-profile source loading now invokes already
+loaded module-local and `user` `term_expansion/2` and `goal_expansion/2` hooks
+left-to-right. A term expansion may yield one clause or a list of clauses, and
+`expand_term/2` exposes the processor's DCG lowering so a hook can generate the
+ordinary clauses used by Scryer's CLP(Z) parser generators. Goal expansion is
+recursive across control constructs and preserves sharing with variables in the
+surrounding clause.
+
+Module-qualified hook clauses such as `user:goal_expansion/2` are also compiled
+with the correct split between procedure ownership and lexical body context. A
+hook defined from a library module therefore lives in `user` while its
+unqualified helper calls still resolve in the defining library. The compiler
+executes hooks with a fresh bounded solver against the partially built program;
+`solver.js` imports clause-selection helpers directly from `program-indexing.js`,
+so this compile-time service remains acyclic. Strict ISO Part 1 mode does not run
+these extension hooks.
+
+The regression corpus covers clause-list generation, variable-sharing goal
+expansion, qualified hook lexical context, and the Scryer pattern where a
+`term_expansion/2` hook calls `expand_term/2` to generate a DCG predicate.
+
+## What still prevents a drop-in Scryer `clpz.pl`
+
+The remaining compatibility work is the supporting Scryer library surface
+(`assoc`, `pairs`, `between`, `dcgs`, `terms`, `error`, `si`, `freeze`,
+`arithmetic`, `debug`, and `format`) at the interfaces expected by that source,
+plus any small builtin gaps exposed while loading those modules. The generated
+predicates and custom Duo DCG `++>` expansion are no longer VM/compiler
+blockers: Scryer's own `term_expansion/2` can now perform that lowering.
+
+These are reusable library 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/expansion-builtins.js

@@ -0,0 +1,99 @@
+// Generic source-expansion helpers exposed to Prolog code.
+//
+// expand_term/2 provides the system part of source expansion that libraries
+// such as Scryer's CLP(Z) use while generating predicates. User-defined
+// term_expansion/2 and goal_expansion/2 are invoked by program preparation in
+// source-expansion.js; keeping this builtin independent of Solver avoids an
+// import cycle through the standard-library registry.
+
+import {
+  ATOM, COMPOUND, Env, atom, compound, deref, flattenConjunction, unify,
+} from './term.js';
+import { expandDcgRuleClause } from './dcg.js';
+import { PrologError } from './errors.js';
+
+function conjunctionFromGoals(goals) {
+  if (goals.length === 0) return atom('true');
+  let body = goals[goals.length - 1];
+  for (let index = goals.length - 2; index >= 0; index--) {
+    body = compound(',', [goals[index], body]);
+  }
+  return body;
+}
+
+export function clauseToSourceTerm(clause) {
+  if (clause == null || clause.kind === 'quad') return null;
+  if (!Array.isArray(clause.body) || clause.body.length === 0) return clause.head;
+  return compound(':-', [clause.head, conjunctionFromGoals(clause.body)]);
+}
+
+export function sourceTermToClauses(term, env = new Env()) {
+  term = deref(term, env);
+  const list = sourceTermList(term, env);
+  if (list != null) {
+    const clauses = [];
+    for (const item of list) clauses.push(...sourceTermToClauses(item, env));
+    return clauses;
+  }
+  if (term.type === COMPOUND && term.name === ':-' && term.arity === 2) {
+    const head = deref(term.args[0], env);
+    const body = deref(term.args[1], env);
+    return [{ head, body: body.type === ATOM && body.name === 'true' ? [] : flattenConjunction(body) }];
+  }
+  if (term.type === COMPOUND && term.name === ':-' && term.arity === 1) {
+    return [{ head: term, body: [] }];
+  }
+  if (term.type === COMPOUND && term.name === '?-' && term.arity >= 1) {
+    return [{ head: term, body: [] }];
+  }
+  if (term.type !== ATOM && term.type !== COMPOUND) {
+    throw new PrologError('type_error(callable)', term);
+  }
+  return [{ head: term, body: [] }];
+}
+
+function sourceTermList(term, env) {
+  const items = [];
+  const seen = new Set();
+  let cursor = deref(term, env);
+  while (cursor.type === COMPOUND && cursor.name === '.' && cursor.arity === 2) {
+    if (seen.has(cursor)) throw new PrologError('type_error(list)', term);
+    seen.add(cursor);
+    items.push(deref(cursor.args[0], env));
+    cursor = deref(cursor.args[1], env);
+  }
+  if (cursor.type === ATOM && cursor.name === '[]') return items;
+  return null;
+}
+
+export function systemExpandTerm(term, module = 'user') {
+  const resolved = deref(term, new Env());
+  if (resolved.type === COMPOUND && resolved.name === '-->' && resolved.arity === 2) {
+    const expanded = expandDcgRuleClause({ head: resolved, body: [] }, module);
+    if (expanded == null) return resolved;
+    return clauseToSourceTerm(expanded);
+  }
+  return resolved;
+}
+
+function* expandTermBuiltin({ goal, env }) {
+  const input = deref(goal.args[0], env);
+  if (input.type === 'var') throw new PrologError('instantiation_error');
+  const expanded = systemExpandTerm(input, goal.module ?? 'user');
+  const next = env.clone();
+  if (unify(goal.args[1], expanded, next)) yield next;
+}
+
+function* expandGoalBuiltin({ goal, env }) {
+  const input = deref(goal.args[0], env);
+  if (input.type === 'var') throw new PrologError('instantiation_error');
+  const next = env.clone();
+  if (unify(goal.args[1], input, next)) yield next;
+}
+
+export const expansionBuiltins = {
+  register(registry) {
+    registry.add('expand_term', 2, expandTermBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('expand_goal', 2, expandGoalBuiltin, { 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).