eyeprolog 1.1.17 → 1.1.18

package/README.md

@@ -91,7 +91,7 @@ noun --> [world] | [prolog].
 %% goal: phrase(sentence, Words)
 ```
 
-EyeProlog also adds 91 public library predicate indicators to its 129-entry ISO
+EyeProlog also adds 99 public library predicate indicators to its 129-entry ISO
 profile. **60 are implemented entirely as ordinary Prolog clauses** in focused
 modules under `src/lib/`; the control predicates and finite-domain
 `library(clpz)` kernel use backtrackable host support.

package/examples/clpz-global-constraints.pl

@@ -0,0 +1,35 @@
+:- use_module(library(clpz)).
+
+% Finite global constraints cover compatibility tables, lexicographic and
+% non-overlapping schedules, value cardinalities with costs, Hamiltonian
+% circuits, distinct-value counting, and three-way integer comparison.
+
+%% goal: advanced_clpz(X0, X1)
+
+advanced_clpz(table, compatible(4, Y, Distinct)) :-
+  tuples_in([[X, Y]], [[1, 2], [1, 5], [4, 0], [4, 3]]),
+  X = 4,
+  nvalue(Distinct, [X, Y]),
+  labeling([], [Y]).
+
+advanced_clpz(schedule, starts([A, B, C])) :-
+  [A, B, C] ins 0..3,
+  lex_chain([[A, B], [B, C]]),
+  serialized([A, B, C], [1, 2, 1]),
+  A #< B,
+  B #< C,
+  labeling([ff], [A, B, C]).
+
+advanced_clpz(cardinality, assignment(Values, Cost, Order)) :-
+  Values = [_, _, _],
+  global_cardinality(Values, [1-2, 3-1],
+    [cost(Cost, [[5, 1], [2, 4], [3, 6]])]),
+  labeling([ff], Values),
+  zcompare(Order, Cost, 10).
+
+advanced_clpz(circuit, successors(Values)) :-
+  Values = [A, B, _, _],
+  circuit(Values),
+  A #= 2,
+  B #= 3,
+  labeling([ff], Values).

package/examples/output/clpz-global-constraints.pl

@@ -0,0 +1,7 @@
+advanced_clpz(table, compatible(4, 0, 2)).
+advanced_clpz(table, compatible(4, 3, 2)).
+advanced_clpz(schedule, starts([0, 1, 3])).
+advanced_clpz(cardinality, assignment([1, 1, 3], 13, >)).
+advanced_clpz(cardinality, assignment([1, 3, 1], 12, >)).
+advanced_clpz(cardinality, assignment([3, 1, 1], 6, <)).
+advanced_clpz(circuit, successors([2, 3, 4, 1])).

package/package.json

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

package/playground.html

@@ -465,6 +465,7 @@
           "chart-parser",
           "clinical-trial-screening",
           "clpz-factorial",
+          "clpz-global-constraints",
           "clpz-n-queens",
           "clpz-resource-allocation",
           "collatz-1000",
@@ -961,7 +962,7 @@
       runButton.disabled = true;
       stopButton.disabled = false;
 
-      const workerUrl = new URL('./src/playground-worker.js?playground=20260807b', location.href);
+      const workerUrl = new URL('./src/playground-worker.js?playground=20260811c', location.href);
       activeWorker = new Worker(workerUrl, { type: 'module' });
       const worker = activeWorker;
       const request = {

package/src/clpz.js

@@ -19,10 +19,17 @@ export const clpzBuiltins = {
     registry.add('eyeprolog__clpz_in', 2, inBuiltin, { deterministic: true, eyePrologLibrary: true });
     registry.add('eyeprolog__clpz_ins', 2, insBuiltin, { deterministic: true, eyePrologLibrary: true });
     registry.add('eyeprolog__clpz_all_distinct', 1, allDistinctBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('eyeprolog__clpz_nvalue', 2, nvalueBuiltin, { deterministic: true, eyePrologLibrary: true });
     registry.add('eyeprolog__clpz_sum', 3, sumBuiltin, { deterministic: true, eyePrologLibrary: true });
     registry.add('eyeprolog__clpz_scalar_product', 4, scalarProductBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('eyeprolog__clpz_tuples_in', 2, tuplesInBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('eyeprolog__clpz_lex_chain', 1, lexChainBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('eyeprolog__clpz_serialized', 2, serializedBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('eyeprolog__clpz_global_cardinality', 3, globalCardinalityBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('eyeprolog__clpz_circuit', 1, circuitBuiltin, { deterministic: true, eyePrologLibrary: true });
     registry.add('eyeprolog__clpz_chain', 2, chainBuiltin, { deterministic: true, eyePrologLibrary: true });
     registry.add('eyeprolog__clpz_element', 3, elementBuiltin, { deterministic: true, eyePrologLibrary: true });
+    registry.add('eyeprolog__clpz_zcompare', 3, zcompareBuiltin, { deterministic: true, eyePrologLibrary: true });
     registry.add('eyeprolog__clpz_labeling', 2, labelingBuiltin, { eyePrologLibrary: true });
     registry.add('eyeprolog__clpz_fd_var', 1, fdVarBuiltin, { deterministic: true, eyePrologLibrary: true });
     registry.add('eyeprolog__clpz_fd_inf', 2, fdBoundBuiltin('inf'), { deterministic: true, eyePrologLibrary: true });
@@ -206,20 +213,30 @@ function domainForRoot(root, env) {
 }
 
 function constrainTermDomain(next, term, values) {
+  const result = narrowTermDomain(next, term, values);
+  return result.ok && clpzStateConsistent(next);
+}
+
+function narrowTermDomain(next, term, values) {
   const resolved = deref(term, next);
   if (resolved.type === NUMBER) {
     const value = integerValue(resolved, next);
-    return values.some((candidate) => candidate === value);
+    return { ok: values.some((candidate) => candidate === value), changed: false };
   }
   if (resolved.type !== VAR) throw new PrologError('type_error(integer)', resolved);
   const existing = domainForRoot(resolved.name, next);
   const narrowed = existing == null ? values : intersectValues(existing, values);
-  if (narrowed.length === 0) return false;
+  if (narrowed.length === 0) return { ok: false, changed: false };
+  const changed = existing == null || existing.length !== narrowed.length ||
+    existing.some((value, index) => value !== narrowed[index]);
+  if (!changed) return { ok: true, changed: false };
   const domains = new Map(storeOf(next).domains);
   domains.set(resolved.name, narrowed);
   updateStore(next, { domains });
-  if (narrowed.length === 1 && !unify(resolved, numberTerm(narrowed[0].toString()), next)) return false;
-  return clpzStateConsistent(next);
+  if (narrowed.length === 1 && !unify(resolved, numberTerm(narrowed[0].toString()), next)) {
+    return { ok: false, changed: false };
+  }
+  return { ok: true, changed: true };
 }
 
 function* inBuiltin({ goal, env }) {
@@ -248,11 +265,36 @@ function listArgument(term, env) {
   return items;
 }
 
+function nestedListArgument(term, env) {
+  return listArgument(term, env).map((item) => listArgument(item, env));
+}
+
+function integerListArgument(term, env) {
+  return listArgument(term, env).map((item) => {
+    const value = integerValue(item, env);
+    if (value == null) throw new PrologError('instantiation_error');
+    return value;
+  });
+}
+
+function integerRange(lower, upper) {
+  const values = [];
+  for (let value = BigInt(lower); value <= BigInt(upper); value++) values.push(value);
+  return values;
+}
+
 function* allDistinctBuiltin({ goal, env }) {
   const next = env.clone();
   if (addGlobal(next, { kind: 'allDistinct', terms: listArgument(goal.args[0], env) })) yield next;
 }
 
+function* nvalueBuiltin({ goal, env }) {
+  const terms = listArgument(goal.args[1], env);
+  const next = env.clone();
+  if (!constrainTermDomain(next, goal.args[0], integerRange(terms.length === 0 ? 0 : 1, terms.length))) return;
+  if (addGlobal(next, { kind: 'nvalue', count: goal.args[0], terms })) yield next;
+}
+
 function* sumBuiltin({ goal, env }) {
   const next = env.clone();
   const relation = relationName(goal.args[1], env);
@@ -269,6 +311,93 @@ function* scalarProductBuiltin({ goal, env }) {
   if (addGlobal(next, { kind: 'scalarProduct', coefficients, terms, relation, value: goal.args[3] })) yield next;
 }
 
+function* tuplesInBuiltin({ goal, env }) {
+  const tuples = nestedListArgument(goal.args[0], env);
+  const relation = nestedListArgument(goal.args[1], env).map((row) => row.map((item) => {
+    const value = integerValue(item, env);
+    if (value == null) throw new PrologError('instantiation_error');
+    return value;
+  }));
+  const next = env.clone();
+  if (addGlobal(next, { kind: 'tuplesIn', tuples, relation })) yield next;
+}
+
+function* lexChainBuiltin({ goal, env }) {
+  const lists = nestedListArgument(goal.args[0], env);
+  if (lists.some((list) => list.length !== (lists[0]?.length ?? 0))) return;
+  const next = env.clone();
+  if (addGlobal(next, { kind: 'lexChain', lists })) yield next;
+}
+
+function* serializedBuiltin({ goal, env }) {
+  const starts = listArgument(goal.args[0], env);
+  const durations = integerListArgument(goal.args[1], env);
+  if (starts.length !== durations.length) throw new PrologError('domain_error(same_length)');
+  if (durations.some((duration) => duration < 0n)) throw new PrologError('domain_error(not_less_than_zero)');
+  const next = env.clone();
+  if (addGlobal(next, { kind: 'serialized', starts, durations })) yield next;
+}
+
+function gccPairs(term, env) {
+  const pairs = listArgument(term, env).map((pair) => {
+    const resolved = deref(pair, env);
+    if (resolved.type !== COMPOUND || resolved.name !== '-' || resolved.arity !== 2) {
+      throw new PrologError('domain_error(gcc_pair)', resolved);
+    }
+    const key = integerValue(resolved.args[0], env);
+    if (key == null) throw new PrologError('instantiation_error');
+    return { key, count: resolved.args[1] };
+  });
+  const keys = new Set(pairs.map(({ key }) => key.toString()));
+  if (keys.size !== pairs.length) throw new PrologError('domain_error(gcc_unique_key_pairs)', deref(term, env));
+  return pairs;
+}
+
+function gccOptions(term, env, rowCount, columnCount) {
+  let cost = null;
+  let matrix = null;
+  for (const option of listArgument(term, env)) {
+    const resolved = deref(option, env);
+    if (resolved.type === COMPOUND && resolved.name === 'consistency' && resolved.arity === 1 &&
+        deref(resolved.args[0], env).type === ATOM && deref(resolved.args[0], env).name === 'value') continue;
+    if (resolved.type === COMPOUND && resolved.name === 'cost' && resolved.arity === 2 && cost == null) {
+      cost = resolved.args[0];
+      matrix = nestedListArgument(resolved.args[1], env).map((row) => row.map((item) => {
+        const value = integerValue(item, env);
+        if (value == null) throw new PrologError('instantiation_error');
+        return value;
+      }));
+      if (matrix.length !== rowCount || matrix.some((row) => row.length !== columnCount)) {
+        throw new PrologError('domain_error(gcc_cost_matrix)', resolved.args[1]);
+      }
+      continue;
+    }
+    throw new PrologError('domain_error(global_cardinality_option)', resolved);
+  }
+  return { cost, matrix };
+}
+
+function* globalCardinalityBuiltin({ goal, env }) {
+  const terms = listArgument(goal.args[0], env);
+  const pairs = gccPairs(goal.args[1], env);
+  const options = gccOptions(goal.args[2], env, terms.length, pairs.length);
+  const keys = pairs.map(({ key }) => key).sort(compareBigInt);
+  const next = env.clone();
+  for (const term of terms) if (!constrainTermDomain(next, term, keys)) return;
+  for (const { count } of pairs) if (!constrainTermDomain(next, count, integerRange(0, terms.length))) return;
+  if (addGlobal(next, { kind: 'globalCardinality', terms, pairs, ...options })) yield next;
+}
+
+function* circuitBuiltin({ goal, env }) {
+  const terms = listArgument(goal.args[0], env);
+  const next = env.clone();
+  if (terms.length > 0) {
+    const values = integerRange(1, terms.length);
+    for (const term of terms) if (!constrainTermDomain(next, term, values)) return;
+  }
+  if (addGlobal(next, { kind: 'circuit', terms })) yield next;
+}
+
 function* chainBuiltin({ goal, env }) {
   const terms = listArgument(goal.args[1], env);
   const relation = relationName(goal.args[0], env);
@@ -282,6 +411,70 @@ function* elementBuiltin({ goal, env }) {
   if (addGlobal(next, { kind: 'element', index: goal.args[0], terms: listArgument(goal.args[1], env), value: goal.args[2] })) yield next;
 }
 
+function* zcompareBuiltin({ goal, env }) {
+  const next = env.clone();
+  if (addGlobal(next, { kind: 'zcompare', order: goal.args[0], left: goal.args[1], right: goal.args[2] })) yield next;
+}
+
+function tupleCandidates(tuple, relation, env) {
+  return relation.filter((row) => row.length === tuple.length && row.every((candidate, index) => {
+    const resolved = deref(tuple[index], env);
+    if (resolved.type === NUMBER) return integerValue(resolved, env) === candidate;
+    if (resolved.type !== VAR) throw new PrologError('type_error(integer)', resolved);
+    const domain = domainForRoot(resolved.name, env);
+    return domain == null || domain.some((value) => value === candidate);
+  }));
+}
+
+function lexPairTruth(left, right, env) {
+  if (left.length !== right.length) return false;
+  for (let index = 0; index < left.length; index++) {
+    const a = expressionValue(left[index], env);
+    const b = expressionValue(right[index], env);
+    if (a == null || b == null) return true;
+    if (a < b) return true;
+    if (a > b) return false;
+  }
+  return true;
+}
+
+function circuitTruth(terms, env) {
+  if (terms.length === 0) return true;
+  const values = terms.map((term) => expressionValue(term, env));
+  const seenValues = new Set();
+  for (let index = 0; index < values.length; index++) {
+    const value = values[index];
+    if (value == null) continue;
+    if (value < 1n || value > BigInt(values.length)) return false;
+    if (values.length > 1 && value === BigInt(index + 1)) return false;
+    const key = value.toString();
+    if (seenValues.has(key)) return false;
+    seenValues.add(key);
+  }
+  if (values.some((value) => value == null)) return true;
+  const visited = new Set();
+  let node = 1;
+  for (let step = 0; step < values.length; step++) {
+    if (visited.has(node)) return false;
+    visited.add(node);
+    node = Number(values[node - 1]);
+  }
+  return node === 1 && visited.size === values.length;
+}
+
+function orderAtom(term, env) {
+  const resolved = deref(term, env);
+  if (resolved.type === VAR) return null;
+  if (resolved.type !== ATOM || !['<', '=', '>'].includes(resolved.name)) {
+    throw new PrologError('domain_error(order)', resolved);
+  }
+  return resolved.name;
+}
+
+function comparedOrder(left, right) {
+  return left < right ? '<' : left > right ? '>' : '=';
+}
+
 function globalTruth(global, env) {
   if (global.kind === 'allDistinct') {
     const seen = new Set();
@@ -294,6 +487,14 @@ function globalTruth(global, env) {
     }
     return true;
   }
+  if (global.kind === 'nvalue') {
+    const values = global.terms.map((term) => expressionValue(term, env));
+    const known = new Set(values.filter((value) => value != null).map(String));
+    const count = expressionValue(global.count, env);
+    if (count == null) return true;
+    if (count < BigInt(known.size) || count > BigInt(known.size + values.filter((value) => value == null).length)) return false;
+    return values.some((value) => value == null) || count === BigInt(known.size);
+  }
   if (global.kind === 'sum') {
     const values = global.terms.map((term) => expressionValue(term, env));
     const right = expressionValue(global.value, env);
@@ -309,6 +510,54 @@ function globalTruth(global, env) {
     for (let i = 0; i < values.length; i++) total += integerValue(global.coefficients[i], env) * values[i];
     return relationTruth(relationTerm(global.relation, numberTerm(total.toString()), global.value), env) !== false;
   }
+  if (global.kind === 'tuplesIn') {
+    return global.tuples.every((tuple) => tupleCandidates(tuple, global.relation, env).length > 0);
+  }
+  if (global.kind === 'lexChain') {
+    for (let index = 1; index < global.lists.length; index++) {
+      if (!lexPairTruth(global.lists[index - 1], global.lists[index], env)) return false;
+    }
+    return true;
+  }
+  if (global.kind === 'serialized') {
+    for (let left = 0; left < global.starts.length; left++) {
+      const a = expressionValue(global.starts[left], env);
+      if (a == null) continue;
+      for (let right = left + 1; right < global.starts.length; right++) {
+        const b = expressionValue(global.starts[right], env);
+        if (b == null) continue;
+        if (a + global.durations[left] > b && b + global.durations[right] > a) return false;
+      }
+    }
+    return true;
+  }
+  if (global.kind === 'globalCardinality') {
+    const values = global.terms.map((term) => expressionValue(term, env));
+    for (const { key, count: countTerm } of global.pairs) {
+      const known = values.filter((value) => value === key).length;
+      const possible = global.terms.filter((term, index) => {
+        if (values[index] != null) return false;
+        const resolved = deref(term, env);
+        const domain = resolved.type === VAR ? domainForRoot(resolved.name, env) : null;
+        return domain == null || domain.some((value) => value === key);
+      }).length;
+      const count = expressionValue(countTerm, env);
+      if (count != null && (count < BigInt(known) || count > BigInt(known + possible))) return false;
+      if (possible === 0 && count != null && count !== BigInt(known)) return false;
+    }
+    if (global.cost != null && values.every((value) => value != null)) {
+      let total = 0n;
+      for (let row = 0; row < values.length; row++) {
+        const column = global.pairs.findIndex(({ key }) => key === values[row]);
+        if (column < 0) return false;
+        total += global.matrix[row][column];
+      }
+      const cost = expressionValue(global.cost, env);
+      if (cost != null && cost !== total) return false;
+    }
+    return true;
+  }
+  if (global.kind === 'circuit') return circuitTruth(global.terms, env);
   if (global.kind === 'chain') {
     for (let i = 1; i < global.terms.length; i++) {
       const truth = relationTruth(relationTerm(global.relation, global.terms[i - 1], global.terms[i]), env);
@@ -325,6 +574,12 @@ function globalTruth(global, env) {
     const right = expressionValue(global.value, env);
     return left == null || right == null || left === right;
   }
+  if (global.kind === 'zcompare') {
+    const order = orderAtom(global.order, env);
+    const left = expressionValue(global.left, env);
+    const right = expressionValue(global.right, env);
+    return order == null || left == null || right == null || order === comparedOrder(left, right);
+  }
   return true;
 }
 
@@ -410,7 +665,82 @@ function propagate(env) {
       }
     }
     for (const global of store.globals) {
-      if (global.kind === 'element') {
+      if (global.kind === 'nvalue') {
+        const values = global.terms.map((term) => expressionValue(term, env));
+        const known = new Set(values.filter((value) => value != null).map(String));
+        const unresolved = values.filter((value) => value == null).length;
+        const result = narrowTermDomain(env, global.count, integerRange(known.size, known.size + unresolved));
+        if (!result.ok) return false;
+        changed ||= result.changed;
+      } else if (global.kind === 'tuplesIn') {
+        for (const tuple of global.tuples) {
+          const candidates = tupleCandidates(tuple, global.relation, env);
+          if (candidates.length === 0) return false;
+          for (let index = 0; index < tuple.length; index++) {
+            const values = [...new Set(candidates.map((row) => row[index].toString()))].map(BigInt).sort(compareBigInt);
+            const result = narrowTermDomain(env, tuple[index], values);
+            if (!result.ok) return false;
+            changed ||= result.changed;
+          }
+        }
+      } else if (global.kind === 'globalCardinality') {
+        const values = global.terms.map((term) => expressionValue(term, env));
+        for (const { key, count: countTerm } of global.pairs) {
+          const known = values.filter((value) => value === key).length;
+          const possibleTerms = global.terms.filter((term, index) => {
+            if (values[index] != null) return false;
+            const resolved = deref(term, env);
+            const domain = resolved.type === VAR ? domainForRoot(resolved.name, env) : null;
+            return domain == null || domain.some((value) => value === key);
+          });
+          const countResult = narrowTermDomain(env, countTerm, integerRange(known, known + possibleTerms.length));
+          if (!countResult.ok) return false;
+          changed ||= countResult.changed;
+          const count = expressionValue(countTerm, env);
+          if (count === BigInt(known)) {
+            for (const term of possibleTerms) {
+              const resolved = deref(term, env);
+              if (resolved.type !== VAR) continue;
+              const domain = domainForRoot(resolved.name, env);
+              const result = narrowTermDomain(env, term, domain.filter((value) => value !== key));
+              if (!result.ok) return false;
+              changed ||= result.changed;
+            }
+          } else if (count === BigInt(known + possibleTerms.length)) {
+            for (const term of possibleTerms) {
+              const result = narrowTermDomain(env, term, [key]);
+              if (!result.ok) return false;
+              changed ||= result.changed;
+            }
+          }
+        }
+        if (global.cost != null && values.every((value) => value != null)) {
+          let total = 0n;
+          for (let row = 0; row < values.length; row++) {
+            const column = global.pairs.findIndex(({ key }) => key === values[row]);
+            if (column < 0) return false;
+            total += global.matrix[row][column];
+          }
+          const result = bindExpressionEquality(global.cost, numberTerm(total.toString()), env);
+          if (!result.ok) return false;
+          changed ||= result.changed;
+        }
+      } else if (global.kind === 'zcompare') {
+        const order = orderAtom(global.order, env);
+        const left = expressionValue(global.left, env);
+        const right = expressionValue(global.right, env);
+        if (left != null && right != null) {
+          const resolvedOrder = atom(comparedOrder(left, right));
+          if (order == null) {
+            if (!unify(global.order, resolvedOrder, env)) return false;
+            changed = true;
+          } else if (order !== resolvedOrder.name) return false;
+        } else if (order === '=') {
+          const result = bindLinearEquality(global.left, global.right, env);
+          if (!result.ok) return false;
+          changed ||= result.changed;
+        }
+      } else if (global.kind === 'element') {
         const index = expressionValue(global.index, env);
         if (index != null) {
           if (index < 1n || index > BigInt(global.terms.length)) return false;

package/src/lib/clpz.pl

@@ -25,13 +25,21 @@
     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,
@@ -75,6 +83,7 @@ ins(Integers, Domain) :- eyeprolog__clpz_ins(Integers, Domain).
 
 all_different(Integers) :- all_distinct(Integers).
 all_distinct(Integers) :- eyeprolog__clpz_all_distinct(Integers).
+nvalue(Count, Integers) :- eyeprolog__clpz_nvalue(Count, Integers).
 
 sum(Integers, Relation, Value) :-
     eyeprolog__clpz_sum(Integers, Relation, Value).
@@ -82,15 +91,27 @@ sum(Integers, Relation, Value) :-
 scalar_product(Coefficients, Integers, Relation, Value) :-
     eyeprolog__clpz_scalar_product(Coefficients, Integers, Relation, Value).
 
+tuples_in(Tuples, Relation) :- eyeprolog__clpz_tuples_in(Tuples, Relation).
+
 labeling(Options, Integers) :-
     eyeprolog__clpz_labeling(Options, Integers).
 
 label(Integers) :- labeling([], Integers).
 indomain(Integer) :- labeling([], [Integer]).
 
+lex_chain(Lists) :- eyeprolog__clpz_lex_chain(Lists).
+serialized(Starts, Durations) :- eyeprolog__clpz_serialized(Starts, Durations).
+
+global_cardinality(Integers, Pairs) :-
+    global_cardinality(Integers, Pairs, []).
+global_cardinality(Integers, Pairs, Options) :-
+    eyeprolog__clpz_global_cardinality(Integers, Pairs, Options).
+
+circuit(Integers) :- eyeprolog__clpz_circuit(Integers).
 chain(Relation, Integers) :- eyeprolog__clpz_chain(Relation, Integers).
 element(Index, Integers, Value) :-
     eyeprolog__clpz_element(Index, Integers, Value).
+zcompare(Order, Left, Right) :- eyeprolog__clpz_zcompare(Order, Left, Right).
 
 fd_var(Integer) :- eyeprolog__clpz_fd_var(Integer).
 fd_inf(Integer, Infimum) :- eyeprolog__clpz_fd_inf(Integer, Infimum).

package/src/playground-worker.js

@@ -1,7 +1,7 @@
 // Browser worker entry used by playground.html.
 // Keep this module free of Node-only imports: it is fetched directly by the
 // browser and is also exercised by test/run-playground.mjs.
-import { createEyePrologRegistry, run } from './index.js?playground=20260807b';
+import { createEyePrologRegistry, run } from './index.js?playground=20260811c';
 
 const registry = createEyePrologRegistry();
 

package/src/standard-library.js

@@ -22,7 +22,7 @@ const moduleFiles = Object.freeze({
 
 const cacheKey = isNode
   ? null
-  : (new URL(import.meta.url).searchParams.get('playground') ?? '20260811b');
+  : (new URL(import.meta.url).searchParams.get('playground') ?? '20260811c');
 
 export const standardLibrarySources = new Map(await Promise.all(
   Object.entries(moduleFiles).map(async ([name, filename]) => [name, {
@@ -48,9 +48,11 @@ export const eyePrologNativeLibraryIndicators = Object.freeze([
   'call_nth/2', 'freeze/2',
   '#>/2', '#</2', '#>=/2', '#=</2', '#=/2', '#\\=/2', '#\\/1',
   '#<==>/2', '#==>/2', '#<==/2', '#\\//2', '#\\/2', '#/\\/2',
-  'in/2', 'ins/2', 'all_different/1', 'all_distinct/1', 'sum/3',
-  'scalar_product/4', 'labeling/2', 'label/1', 'indomain/1', 'chain/2',
-  'element/3', 'fd_var/1', 'fd_inf/2', 'fd_sup/2', 'fd_size/2', 'fd_dom/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',
 ]);
 export const eyePrologPortableLibraryIndicators = Object.freeze([
   'sumall/3', 'aggregate_min/5', 'aggregate_max/5',

package/test/run-regression.mjs

@@ -1438,20 +1438,21 @@ open(X) :- candidate(X), \\+ closed(X).
         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, 145, 'EyeProlog registry contains ISO definitions and private library adapters');
+        assertEqual(library.defs.size, 152, 'EyeProlog registry contains ISO definitions 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(registeredNativeEyePrologLibraryNames().length, 31, 'public native EyeProlog builtin count');
+        assertEqual(registeredNativeEyePrologLibraryNames().length, 39, 'public native EyeProlog builtin count');
         assertEqual(eyePrologPortableLibraryIndicators.length, 60, 'portable Prolog library count');
-        assertEqual(eyePrologNativeLibraryIndicators.length, 31, 'native host library count');
+        assertEqual(eyePrologNativeLibraryIndicators.length, 39, 'native host library count');
         assertEqual(eyePrologNativeLibraryIndicators.slice(0, 2).join(','), 'call_nth/2,freeze/2', 'control predicates requiring host support');
-        assertEqual(eyePrologLibraryIndicators.length, 91, 'complete EyeProlog library surface');
+        assertEqual(eyePrologLibraryIndicators.length, 99, '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');
         assertEqual(registry.get('eyeprolog__freeze', 2), null, 'private freeze adapter is absent from ISO registry');
         assertEqual(Boolean(library.get('eyeprolog__freeze', 2)), true, 'private freeze 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(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');
@@ -1545,6 +1546,19 @@ contradiction :- Z in 1..3, Z = 4.
           'answer(1, 4, 1).\nanswer(2, 3, 0).\n', 'CLP(Z) constrained answers');
       },
     },
+    {
+      name: 'CLP(Z) finite global constraints match the portable example',
+      run: () => {
+        const filename = path.join(packageRoot, 'examples', 'clpz-global-constraints.pl');
+        const source = fs.readFileSync(filename, 'utf8');
+        const program = Program.parseSources([{ text: source, filename }]);
+        assertEqual(program.findGroup('tuples_in', 2)?.module, 'clpz', 'tuples_in/2 module');
+        assertEqual(program.findGroup('global_cardinality', 3)?.module, 'clpz', 'global_cardinality/3 module');
+        assertEqual(program.findGroup('circuit', 1)?.module, 'clpz', 'circuit/1 module');
+        const expected = fs.readFileSync(path.join(packageRoot, 'examples', 'output', 'clpz-global-constraints.pl'), 'utf8');
+        assertEqual(run(program, { goal: 'advanced_clpz(X0, X1)' }).stdout, expected, 'global constraint answers');
+      },
+    },
     {
       name: 'Part 2 modules isolate predicates and support selective imports',
       run: () => {

package/the-art-of-eyeprolog.md

@@ -5762,14 +5762,14 @@ so side effects occur in Prolog execution order.
 
 ### The EyeProlog library
 
-EyeProlog exposes **91 library predicate indicators** in addition to the 129
+EyeProlog exposes **99 library predicate indicators** in addition to the 129
 indicators in its isolated ISO profile. **60 are implemented entirely as
-ordinary Prolog clauses** in focused modules under `src/lib/`. The remaining 31
+ordinary Prolog clauses** in focused modules under `src/lib/`. The remaining 39
 are public wrappers around backtrackable host support: Prologue `call_nth/2` and
-`freeze/2`, plus the 29-predicate finite-domain `library(clpz)` kernel. The
-resulting normal EyeProlog language surface is therefore **220 public predicate
+`freeze/2`, plus the 37-predicate finite-domain `library(clpz)` kernel. The
+resulting normal EyeProlog language surface is therefore **228 public predicate
 indicators**. Internally, the runtime registry contains the 129 ISO definitions
-plus 16 private library adapters; public relations remain module source clauses.
+plus 23 private library adapters; public relations remain module source clauses.
 
 The sources are `src/lib/aggregate.pl`, `src/lib/clpz.pl`, `src/lib/comparison.pl`,
 `src/lib/dates.pl`, `src/lib/iso_ext.pl`, `src/lib/lists.pl`,
@@ -5799,7 +5799,7 @@ between solution branches.
 | Module | Exported predicate indicators |
 | --- | --- |
 | `library(aggregate)` | `sumall/3`, `aggregate_min/5`, `aggregate_max/5` |
-| `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`, `sum/3`, `scalar_product/4`, `labeling/2`, `label/1`, `indomain/1`, `chain/2`, `element/3`, `fd_var/1`, `fd_inf/2`, `fd_sup/2`, `fd_size/2`, `fd_dom/2` |
+| `library(clpz)` | `#>/2`, `#</2`, `#>=/2`, `#=</2`, `#=/2`, `#\=/2`, `#\/1`, `#<==>/2`, `#==>/2`, `#<==/2`, `#\//2`, `#\/2`, `#/\/2`, `in/2`, `ins/2`, `all_different/1`, `all_distinct/1`, `nvalue/2`, `sum/3`, `scalar_product/4`, `tuples_in/2`, `labeling/2`, `label/1`, `indomain/1`, `lex_chain/1`, `serialized/2`, `global_cardinality/2`, `global_cardinality/3`, `circuit/1`, `chain/2`, `element/3`, `zcompare/3`, `fd_var/1`, `fd_inf/2`, `fd_sup/2`, `fd_size/2`, `fd_dom/2` |
 | `library(comparison)` | `lt/2`, `gt/2`, `le/2`, `ge/2` |
 | `library(dates)` | `difference/3` |
 | `library(iso_ext)` | `countall/2`, `forall/2`, `succ/2`, `cfor/3`, `findall/4`, `variant/2` |
@@ -5816,10 +5816,13 @@ between solution branches.
 programming over integers. Its first implementation step 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, and domain reflection. Constraints are kept
-in the logical environment, so failed alternatives cannot leak domains into
-later branches. The full Trealla library also contains additional global
-constraints and unbounded-domain propagation that are not yet exported here.
+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. The full Trealla library also contains automata,
+cumulative and two-dimensional scheduling constraints, and unbounded-domain
+propagation that are not yet exported here.
 
 `library(iso_ext)` collects extensions commonly found in mature Prolog
 systems. `forall/2` checks an action for every solution of a condition;
@@ -6362,7 +6365,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 **209 self-contained runnable programs**. Every
+top-level directory contains **210 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
@@ -6411,6 +6414,7 @@ mode at a time.
 | Program | Standard facility | Checked answer |
 | --- | --- | --- |
 | [CLP(Z) factorial](https://github.com/eyereasoner/eyeprolog/blob/main/examples/clpz-factorial.pl) | Declarative predecessor and product constraints propagate a factorial without mode-sensitive `is/2`. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/clpz-factorial.pl) |
+| [CLP(Z) global constraints](https://github.com/eyereasoner/eyeprolog/blob/main/examples/clpz-global-constraints.pl) | Compatibility tables, lexicographic and serialized schedules, global cardinality with costs, circuits, value counting, and integer comparison. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/clpz-global-constraints.pl) |
 | [CLP(Z) N-queens](https://github.com/eyereasoner/eyeprolog/blob/main/examples/clpz-n-queens.pl) | Six-queens using finite domains, delayed diagonal constraints, `all_distinct/1`, and first-fail labeling. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/clpz-n-queens.pl) |
 | [CLP(Z) resource allocation](https://github.com/eyereasoner/eyeprolog/blob/main/examples/clpz-resource-allocation.pl) | Resource assignment using `element/3`, `sum/3`, `scalar_product/4`, reification, labeling options, and domain reflection. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/clpz-resource-allocation.pl) |
 | [Combinatorics Findall Sort](https://github.com/eyereasoner/eyeprolog/blob/main/examples/combinatorics-findall-sort.pl) | Eyelet-inspired combinations example using `findall/3` and ISO `sort/2`. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/combinatorics-findall-sort.pl) |