seam-lang 2.0.0

package/examples/braking-safety-worlds.pl

@@ -0,0 +1,69 @@
+% EYE reasoning-inspired example: braking safety in alternative worlds.
+%
+% Four simplified models classify the same road scenarios. The example is not a
+% real safety calculator; it demonstrates rule-level model comparison.
+
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
+materialize(safeInWorld, 2).
+materialize(riskyInWorld, 2).
+materialize(status, 2).
+materialize(reason, 2).
+
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+scenario(city_dry, 13.9, 0.8, 40.0).
+scenario(highway_dry_short_gap, 27.8, 0.8, 60.0).
+scenario(city_wet, 13.9, 0.4, 40.0).
+scenario(city_ice, 13.9, 0.2, 30.0).
+
+world(w0, "physics-based stopping distance with reaction time").
+world(w1, "simplified braking-only rule without reaction time").
+world(w2, "naive dry-road friction assumption").
+world(w3, "cautious factor over the physics model").
+
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
+stop_distance(Scenario, w0, Distance) :-
+  scenario(Scenario, V, Mu, Avail),
+  mul(V, 1.0, Reaction),
+  pow(V, 2.0, V2),
+  mul(Mu, 2.0, M2),
+  mul(M2, 9.8, Denom),
+  div(V2, Denom, Braking),
+  add(Reaction, Braking, Distance).
+
+stop_distance(Scenario, w1, Distance) :-
+  scenario(Scenario, V, Mu, Avail),
+  pow(V, 2.0, V2),
+  mul(Mu, 2.0, M2),
+  mul(M2, 10.0, Denom),
+  div(V2, Denom, Distance).
+
+stop_distance(Scenario, w2, Distance) :-
+  scenario(Scenario, V, Mu, Avail),
+  pow(V, 2.0, V2),
+  div(V2, 14.0, Distance).
+
+stop_distance(Scenario, w3, Distance) :-
+  stop_distance(Scenario, w0, W0distance),
+  mul(W0distance, 1.5, Distance).
+
+safe_in_world(Scenario, World) :-
+  scenario(Scenario, V, Mu, Avail),
+  stop_distance(Scenario, World, Distance),
+  le(Distance, Avail).
+
+risky_in_world(Scenario, World) :-
+  scenario(Scenario, V, Mu, Avail),
+  stop_distance(Scenario, World, Distance),
+  gt(Distance, Avail).
+
+pattern_matches(report) :-
+  safe_in_world(city_dry, w0), safe_in_world(city_dry, w1), safe_in_world(city_dry, w2), safe_in_world(city_dry, w3),
+  risky_in_world(highway_dry_short_gap, w0), risky_in_world(highway_dry_short_gap, w3),
+  safe_in_world(highway_dry_short_gap, w1), safe_in_world(highway_dry_short_gap, w2),
+  safe_in_world(city_wet, w0), safe_in_world(city_wet, w1), safe_in_world(city_wet, w2), risky_in_world(city_wet, w3),
+  risky_in_world(city_ice, w0), risky_in_world(city_ice, w1), risky_in_world(city_ice, w3), safe_in_world(city_ice, w2).
+
+safeInWorld(Scenario, World) :- safe_in_world(Scenario, World).
+riskyInWorld(Scenario, World) :- risky_in_world(Scenario, World).
+status(braking_safety_worlds, expected_world_pattern) :- pattern_matches(report).
+reason(braking_safety_worlds, "simplified and naive worlds can be optimistic while the cautious world tightens the reference model") :- pattern_matches(report).

package/examples/buck-converter-design.pl

@@ -0,0 +1,83 @@
+% Engineering example: buck-converter ripple check.
+%
+% A simplified continuous-conduction buck converter model computes duty cycle,
+% inductor ripple current, capacitor ripple voltage, and checks design limits.
+
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
+%
+% The constants describe one regulator design. The rules intentionally keep
+% each engineering equation separate so proof output can point to the exact
+% calculation that made the design pass or fail.
+materialize(dutyCycle, 2).
+materialize(inductorRipple_A, 2).
+materialize(rippleRatio, 2).
+materialize(capacitorRipple_V, 2).
+materialize(status, 2).
+materialize(reason, 2).
+
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+converter(regulator1, inputVoltage_V, 24.0).
+converter(regulator1, outputVoltage_V, 5.0).
+converter(regulator1, loadCurrent_A, 2.0).
+converter(regulator1, switchingFrequency_Hz, 500000.0).
+converter(regulator1, inductance_H, 0.000022).
+converter(regulator1, capacitance_F, 0.000047).
+limit(regulator1, maxRippleRatio, 0.30).
+limit(regulator1, maxOutputRipple_V, 0.05).
+
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
+duty_cycle(Converter, Duty) :-
+  converter(Converter, outputVoltage_V, Outputvoltage),
+  converter(Converter, inputVoltage_V, Inputvoltage),
+  div(Outputvoltage, Inputvoltage, Duty).
+
+inductor_ripple_current(Converter, Ripplecurrent) :-
+  converter(Converter, inputVoltage_V, Inputvoltage),
+  converter(Converter, outputVoltage_V, Outputvoltage),
+  converter(Converter, inductance_H, Inductance),
+  converter(Converter, switchingFrequency_Hz, Frequency),
+  duty_cycle(Converter, Duty),
+  sub(Inputvoltage, Outputvoltage, Voltageacrossinductor),
+  mul(Voltageacrossinductor, Duty, Numerator),
+  mul(Inductance, Frequency, Denominator),
+  div(Numerator, Denominator, Ripplecurrent).
+
+ripple_ratio(Converter, Ratio) :-
+  inductor_ripple_current(Converter, Ripplecurrent),
+  converter(Converter, loadCurrent_A, Loadcurrent),
+  div(Ripplecurrent, Loadcurrent, Ratio).
+
+capacitor_ripple_voltage(Converter, Ripplevoltage) :-
+  inductor_ripple_current(Converter, Ripplecurrent),
+  converter(Converter, switchingFrequency_Hz, Frequency),
+  converter(Converter, capacitance_F, Capacitance),
+  mul(8.0, Frequency, Eightf),
+  mul(Eightf, Capacitance, Denominator),
+  div(Ripplecurrent, Denominator, Ripplevoltage).
+
+% within_ripple_limits/1 is the design gate for ripple current and output voltage.
+within_ripple_limits(Converter) :-
+  ripple_ratio(Converter, Ratio),
+  limit(Converter, maxRippleRatio, Maxratio),
+  lt(Ratio, Maxratio),
+  capacitor_ripple_voltage(Converter, Ripplevoltage),
+  limit(Converter, maxOutputRipple_V, Maxripplevoltage),
+  lt(Ripplevoltage, Maxripplevoltage).
+
+dutyCycle(Converter, Duty) :-
+  duty_cycle(Converter, Duty).
+
+inductorRipple_A(Converter, Ripplecurrent) :-
+  inductor_ripple_current(Converter, Ripplecurrent).
+
+rippleRatio(Converter, Ratio) :-
+  ripple_ratio(Converter, Ratio).
+
+capacitorRipple_V(Converter, Ripplevoltage) :-
+  capacitor_ripple_voltage(Converter, Ripplevoltage).
+
+status(Converter, stable_ripple_design) :-
+  within_ripple_limits(Converter).
+
+reason(Converter, "inductor-current and output-voltage ripple are below design limits") :-
+  within_ripple_limits(Converter).

package/examples/cache-performance.pl

@@ -0,0 +1,56 @@
+% Technology example: cache performance summary.
+%
+% A service has cache hits and misses with different response latencies. The
+% rules compute hit rate and weighted average latency, then classify whether
+% the cache is effective.
+
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
+materialize(hitRate, 2).
+materialize(averageLatency_ms, 2).
+materialize(status, 2).
+materialize(reason, 2).
+
+% cache_sample/5 contains hits, misses, and the two latency classes; threshold/3
+% contains the operational targets used by the status rule.
+cache_sample(api_cache, 8600.0, 1400.0, 5.0, 80.0).
+threshold(api_cache, minimum_hit_rate, 0.80).
+threshold(api_cache, maximum_average_latency_ms, 20.0).
+
+% The rules compute total requests, hit rate, and weighted latency before
+% applying both acceptance thresholds together.
+total_requests(Cache, Total) :-
+  cache_sample(Cache, Hits, Misses, _hitlatency, _misslatency),
+  add(Hits, Misses, Total).
+
+hit_rate(Cache, Rate) :-
+  cache_sample(Cache, Hits, _misses, _hitlatency, _misslatency),
+  total_requests(Cache, Total),
+  div(Hits, Total, Rate).
+
+average_latency(Cache, Average) :-
+  cache_sample(Cache, Hits, Misses, Hitlatency, Misslatency),
+  mul(Hits, Hitlatency, Hitcost),
+  mul(Misses, Misslatency, Misscost),
+  add(Hitcost, Misscost, Totalcost),
+  total_requests(Cache, Total),
+  div(Totalcost, Total, Average).
+
+cache_effective(Cache) :-
+  hit_rate(Cache, Rate),
+  threshold(Cache, minimum_hit_rate, Minimumrate),
+  gt(Rate, Minimumrate),
+  average_latency(Cache, Average),
+  threshold(Cache, maximum_average_latency_ms, Maximumlatency),
+  lt(Average, Maximumlatency).
+
+hitRate(Cache, Rate) :-
+  hit_rate(Cache, Rate).
+
+averageLatency_ms(Cache, Average) :-
+  average_latency(Cache, Average).
+
+status(Cache, cache_effective) :-
+  cache_effective(Cache).
+
+reason(Cache, "hit rate is above target and average latency is below limit") :-
+  cache_effective(Cache).

package/examples/canary-release.pl

@@ -0,0 +1,51 @@
+% Technology example: canary release decision.
+%
+% A canary deployment is rolled back when its measured error rate exceeds the
+% allowed budget, even when latency is still acceptable.
+
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
+materialize(errorRate, 2).
+materialize(p95Latency_ms, 2).
+materialize(latencyCheck, 2).
+materialize(status, 2).
+materialize(reason, 2).
+
+% canary/4 records request count, error count, and p95 latency; thresholds
+% make the rollout policy explicit data rather than constants hidden in rules.
+canary(canary42, 5000.0, 75.0, 180.0).
+threshold(canary42, maximum_error_rate, 0.01).
+threshold(canary42, maximum_p95_latency_ms, 200.0).
+
+% The latency and error-budget checks are independent so the final rollback
+% reason can point to the failing guard.
+error_rate(Release, Rate) :-
+  canary(Release, Requests, Errors, _p95latency),
+  div(Errors, Requests, Rate).
+
+latency_ok(Release) :-
+  canary(Release, _requests, _errors, P95latency),
+  threshold(Release, maximum_p95_latency_ms, Maximum),
+  lt(P95latency, Maximum).
+
+error_budget_exceeded(Release) :-
+  error_rate(Release, Rate),
+  threshold(Release, maximum_error_rate, Maximum),
+  gt(Rate, Maximum).
+
+rollback_recommended(Release) :-
+  error_budget_exceeded(Release).
+
+errorRate(Release, Rate) :-
+  error_rate(Release, Rate).
+
+p95Latency_ms(Release, P95latency) :-
+  canary(Release, _requests, _errors, P95latency).
+
+latencyCheck(Release, ok) :-
+  latency_ok(Release).
+
+status(Release, rollback_recommended) :-
+  rollback_recommended(Release).
+
+reason(Release, "canary error rate exceeds the allowed budget") :-
+  rollback_recommended(Release).

package/examples/cat-koko.pl

@@ -0,0 +1,24 @@
+% Cat Koko, adapted from Eyeling's examples/cat-koko.n3.
+%
+% The Eyeling output contains two existential witnesses. seam has no blank
+% node constructor in the portable core, so this adaptation names those
+% witnesses sk_0 and sk_1.
+
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
+materialize(type, 2).
+materialize(is, 2).
+
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+animal(koko).
+
+witness(cat, sk_0).
+witness(british_short_hair, sk_1).
+
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
+type(X, cat) :- animal(koko), witness(cat, X).
+type(X, british_short_hair) :- animal(koko), witness(british_short_hair, X).
+
+is(test, true) :-
+  type(X, cat),
+  type(Y, british_short_hair),
+  neq(X, Y).

package/examples/catalan-convolution.pl

@@ -0,0 +1,37 @@
+% Catalan numbers by tabled convolution.
+%
+% catalan(N,C) sums all splits of N-1 into left and right substructures.  The same
+% Catalan values appear in binary tree shapes, parenthesizations, and polygon
+% triangulations, shown here with small wrapper predicates.
+materialize(catalan_answer, 2).
+
+table(catalan, 2).
+
+% C_0 = 1; higher values are computed by the convolution sum.
+catalan(0, 1).
+catalan(N, C) :-
+  gt(N, 0),
+  sub(N, 1, N1),
+  sumall(Product,
+    (between(0, N1, I),
+     sub(N1, I, J),
+     catalan(I, A),
+     catalan(J, B),
+     mul(A, B, Product)),
+    C).
+
+% An n-gon has C_(n-2) triangulations.
+polygon_triangulations(Sides, Count) :-
+  ge(Sides, 3),
+  sub(Sides, 2, N),
+  catalan(N, Count).
+
+parenthesizations(Factors, Count) :-
+  ge(Factors, 1),
+  sub(Factors, 1, N),
+  catalan(N, Count).
+
+catalan_answer(catalan_12, C) :- catalan(12, C).
+catalan_answer(triangulations_14_gon, Count) :- polygon_triangulations(14, Count).
+catalan_answer(parenthesizations_13_factors, Count) :- parenthesizations(13, Count).
+catalan_answer(first_ten_sum, Sum) :- sumall(C, (between(0, 9, N), catalan(N, C)), Sum).

package/examples/cdcl-sat-solver.pl

@@ -0,0 +1,65 @@
+% A tiny CDCL-style SAT trace with one learned clause.
+%
+% Industrial CDCL solvers use watched literals, mutable trails, non-chronological
+% backjumping, clause databases, restarts, and activity heuristics.  Seam has
+% no mutable state or destructive trail updates, so this example models one small
+% conflict-analysis episode as relations over immutable terms.
+%
+% Formula:
+%   c1: not(a) or c
+%   c2: not(c)
+%   c3: a or b
+%
+% Decision a=true forces c=true by c1, which conflicts with c2.  Resolving the
+% reason c1 with the conflict c2 learns not(a).  After backjumping, learned
+% not(a) forces a=false, c2 gives c=false, and c3 forces b=true.
+
+materialize(cdclAnswer, 2).
+
+clause(c1, [neg(a), pos(c)]).
+clause(c2, [neg(c)]).
+clause(c3, [pos(a), pos(b)]).
+
+% Initial trail before conflict analysis.
+initial_value(a, true, decision(level1)).
+initial_value(c, true, implied_by(c1)).
+
+% The current trail makes a literal true or false.
+lit_true(pos(Var), Value_rel) :- call_value(Value_rel, Var, true, _).
+lit_true(neg(Var), Value_rel) :- call_value(Value_rel, Var, false, _).
+lit_false(pos(Var), Value_rel) :- call_value(Value_rel, Var, false, _).
+lit_false(neg(Var), Value_rel) :- call_value(Value_rel, Var, true, _).
+
+% Seam cannot pass predicates as first-class values, so this small dispatcher
+% lets the same literal helpers inspect either the initial or final trail.
+call_value(initial, Var, Value, Reason) :- initial_value(Var, Value, Reason).
+call_value(final, Var, Value, Reason) :- final_value(Var, Value, Reason).
+
+% A clause is conflicting when all of its literals are false under a trail.
+conflict(Trail, Clause) :-
+  clause(Clause, Literals),
+  forall(member(Literal, Literals), lit_false(Literal, Trail)).
+
+% The learned clause for this tiny implication graph is obtained by resolving
+% the conflict clause not(c) with c's reason not(a) or c, yielding not(a).
+learned_clause(l1, [neg(a)]).
+learned_from(l1, resolve(c2, c1, pivot(c))).
+
+% After backjumping, the learned unit clause fixes a=false.  Then the original
+% clauses imply c=false and b=true.
+final_value(a, false, learned(l1)).
+final_value(c, false, unit(c2)).
+final_value(b, true, unit(c3)).
+
+model_satisfies_clause(Trail, Clause) :-
+  clause(Clause, Literals),
+  member(Literal, Literals),
+  lit_true(Literal, Trail).
+
+final_model_ok(ok) :- forall(clause(Name, _), model_satisfies_clause(final, Name)).
+
+cdclAnswer(conflict_clause, Clause) :- conflict(initial, Clause).
+cdclAnswer(learned_clause, Literals) :- learned_clause(l1, Literals).
+cdclAnswer(learned_from, Reason) :- learned_from(l1, Reason).
+cdclAnswer(final_value(Var), Value) :- final_model_ok(ok), final_value(Var, Value, _).
+cdclAnswer(note, "one learned clause makes the final model satisfy all original clauses") :- final_model_ok(ok).

package/examples/chart-parser.pl

@@ -0,0 +1,65 @@
+% A tiny tabled chart parser for a context-free grammar.
+%
+% span(Sentence, Category, Start, End) is the dynamic-programming chart item:
+% Category covers a half-open token interval.  Memoizing span/4 turns recursive
+% grammar recognition into chart parsing, so ambiguous phrases share subparses.
+materialize(chart_parser_answer, 2).
+
+table(span, 4).
+
+% Two sample sentences share the same tiny grammar but have different parse counts.
+
+sentence(command, 5).
+sentence(ambiguous_pp, 8).
+
+word(command, 0, the).
+word(command, 1, robot).
+word(command, 2, moves).
+word(command, 3, the).
+word(command, 4, box).
+
+word(ambiguous_pp, 0, the).
+word(ambiguous_pp, 1, robot).
+word(ambiguous_pp, 2, sees).
+word(ambiguous_pp, 3, the).
+word(ambiguous_pp, 4, box).
+word(ambiguous_pp, 5, with).
+word(ambiguous_pp, 6, the).
+word(ambiguous_pp, 7, telescope).
+
+terminal(det, the).
+terminal(noun, robot).
+terminal(noun, box).
+terminal(noun, telescope).
+terminal(verb, moves).
+terminal(verb, sees).
+terminal(prep, with).
+
+rule(s, np, vp).
+rule(np, det, noun).
+rule(np, np, pp).
+rule(vp, verb, np).
+rule(vp, vp, pp).
+rule(pp, prep, np).
+
+% Lexical chart items come directly from words and terminal categories.
+span(Sentence, Category, Start, End) :-
+  word(Sentence, Start, Token),
+  terminal(Category, Token),
+  add(Start, 1, End).
+% Nonterminal chart items split the interval at a Middle point.
+span(Sentence, Category, Start, End) :-
+  rule(Category, Left, Right),
+  span(Sentence, Left, Start, Middle),
+  span(Sentence, Right, Middle, End).
+
+chart_parser_answer(parsed, Sentence) :-
+  sentence(Sentence, Length),
+  span(Sentence, s, 0, Length).
+chart_parser_answer(parse_count, count(Sentence, Count)) :-
+  sentence(Sentence, Length),
+  countall(span(Sentence, s, 0, Length), Count).
+chart_parser_answer(noun_phrase_count, count(Sentence, Count)) :-
+  sentence(Sentence, Length),
+  countall(span(Sentence, np, _start, _end), Count),
+  gt(Length, 0).

package/examples/clinical-trial-screening.pl

@@ -0,0 +1,97 @@
+% Representative example: clinical-trial screening.
+%
+% The program models a small diabetes trial screening workflow. Helper
+% predicates keep the inclusion/exclusion logic separate from the concise
+% public relation report.
+
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
+%
+% Inclusion criteria are positive requirements; exclusion criteria veto a
+% candidate even when the inclusion checks pass. The emitted reason/2 facts are
+% the audit trail a coordinator would need for a screen-failure report.
+materialize(type, 2).
+materialize(status, 2).
+materialize(reason, 2).
+
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+patient(p001).
+patient(p002).
+patient(p003).
+patient(p004).
+
+age(p001, 54).
+age(p002, 67).
+age(p003, 31).
+age(p004, 45).
+
+diagnosis(p001, type2_diabetes).
+diagnosis(p002, type2_diabetes).
+diagnosis(p003, type2_diabetes).
+diagnosis(p004, type2_diabetes).
+
+lab(p001, hba1c_pct, 8.4).
+lab(p002, hba1c_pct, 7.9).
+lab(p003, hba1c_pct, 9.1).
+lab(p004, hba1c_pct, 6.4).
+
+lab(p001, egfr_ml_min, 83.0).
+lab(p002, egfr_ml_min, 38.0).
+lab(p003, egfr_ml_min, 91.0).
+lab(p004, egfr_ml_min, 72.0).
+
+condition(p003, pregnant).
+
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
+inclusion_adult(Patient) :-
+  patient(Patient),
+  age(Patient, Age),
+  ge(Age, 18).
+
+inclusion_diagnosis(Patient) :-
+  diagnosis(Patient, type2_diabetes).
+
+inclusion_hba1c(Patient) :-
+  lab(Patient, hba1c_pct, Hba1c),
+  ge(Hba1c, 7.0),
+  le(Hba1c, 10.5).
+
+exclusion_renal(Patient) :-
+  lab(Patient, egfr_ml_min, Egfr),
+  lt(Egfr, 45.0).
+
+exclusion_pregnancy(Patient) :-
+  condition(Patient, pregnant).
+
+% A patient is eligible only when all inclusion checks pass and no exclusion is proven.
+screen_eligible(Patient) :-
+  inclusion_adult(Patient),
+  inclusion_diagnosis(Patient),
+  inclusion_hba1c(Patient),
+  not(exclusion_renal(Patient)),
+  not(exclusion_pregnancy(Patient)).
+
+screen_fail(Patient) :- exclusion_renal(Patient).
+screen_fail(Patient) :- exclusion_pregnancy(Patient).
+screen_fail(Patient) :- patient(Patient), not(inclusion_hba1c(Patient)).
+
+type(Patient, trial_candidate) :-
+  screen_eligible(Patient).
+
+status(Patient, eligible) :-
+  screen_eligible(Patient).
+
+reason(Patient, "meets inclusion criteria and no listed exclusion") :-
+  screen_eligible(Patient).
+
+status(Patient, screen_fail) :-
+  screen_fail(Patient).
+
+reason(Patient, "eGFR below renal safety threshold") :-
+  exclusion_renal(Patient).
+
+reason(Patient, "pregnancy exclusion applies") :-
+  exclusion_pregnancy(Patient).
+
+reason(Patient, "HbA1c is outside protocol range") :-
+  patient(Patient),
+  not(inclusion_hba1c(Patient)).

package/examples/collatz-1000.pl

@@ -0,0 +1,45 @@
+% Collatz conjecture suite translated from Eyeling's examples/collatz-1000.n3.
+% It enumerates starts N = 1000, 999, ..., 1 by deriving N = 1000 - N0
+% from a repeat relation, then materializes each full trajectory.
+%
+% Source N3:
+% https://raw.githubusercontent.com/eyereasoner/eyeling/refs/heads/main/examples/collatz-1000.n3
+
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
+% table/2 caches shared suffix trajectories so the 1000 starts do not recompute
+% the same Collatz tails hundreds of times.
+materialize(collatzTrajectory, 2).
+table(collatz, 2).
+
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% The N3 source defines repeat/2 recursively; this Seam version uses the
+% equivalent bounded generator so the 1000-case regression remains stack-safe.
+
+% Query / materialization of the test suite.
+% Generate N in {1000..1} and ask the backward-defined collatz/2 predicate
+% for the full trajectory list M.
+collatzTrajectory(N, M) :-
+  repeat(1000, N0),
+  sub(1000, N0, N),
+  collatz(N, M).
+
+% Range generator.
+% repeat(N, I) enumerates all integers I in the half-open interval [0..N-1].
+repeat(N, I) :-
+  sub(N, 1, Last),
+  between(0, Last, I).
+
+% Backward Collatz relation.
+% collatz(N, M) relates a start value N to its full trajectory list M.
+collatz(1, [1]).
+collatz(N, [N|J]) :-
+  gt(N, 1),
+  mod(N, 2, 0),
+  div(N, 2, N1),
+  collatz(N1, J).
+collatz(N, [N|J]) :-
+  gt(N, 1),
+  mod(N, 2, 1),
+  mul(3, N, T),
+  add(T, 1, N1),
+  collatz(N1, J).

package/examples/combinatorics-findall-sort.pl

@@ -0,0 +1,38 @@
+% Eyelet-inspired combinations example using findall/3 and sort/2.
+%
+% combination/3 generates the same subset in several selection orders.  findall/3
+% collects those candidates, and sort/2 canonicalizes the list so each unordered
+% 3-combination of five items is reported once.
+materialize(combinations, 2).
+materialize(count, 2).
+materialize(reason, 2).
+
+% select/3 nondeterministically removes one item from a list; because it is an
+% ordinary rule, the example also demonstrates user-level list recursion.
+select(Item, [Item | Rest], Rest).
+% The recursive clause keeps the non-selected head and searches the tail.
+select(Item, [Head | Tail], [Head | Rest]) :-
+  select(Item, Tail, Rest).
+
+% combination/3 builds an unordered K-combination by repeated selection.
+combination(0, _items, []).
+combination(I, Items, Combination) :-
+  gt(I, 0),
+  select(Item, Items, Remaining),
+  sub(I, 1, J),
+  combination(J, Remaining, Partial),
+  sort([Item | Partial], Combination).
+
+% findall collects all generation orders; sort canonicalizes and deduplicates.
+unique_combinations(K, Items, Unique) :-
+  findall(C, combination(K, Items, C), All),
+  sort(All, Unique).
+
+combinations(combinations_5_choose_3, Unique) :-
+  unique_combinations(3, [1, 2, 3, 4, 5], Unique).
+
+count(combinations_5_choose_3, Count) :-
+  unique_combinations(3, [1, 2, 3, 4, 5], Unique),
+  length(Unique, Count).
+
+reason(combinations_5_choose_3, "findall gathers generated combinations and sort removes duplicates").