eyelang 1.5.3 → 1.5.4

package/examples/epidemic-policy.pl

@@ -1,12 +1,15 @@
 % EYE-inspired epidemic policy choice.
 % Policies are evaluated by estimated reproduction risk and social cost.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(riskScore, 2).
 materialize(cost, 2).
 materialize(status, 2).
 materialize(recommendedPolicy, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Candidate interventions combine vaccination and mask factors.
 policy(no_mandate).
 policy(vaccination_campaign).
 policy(indoor_masks).
@@ -29,6 +32,8 @@ policy_cost(vaccination_campaign, 3).
 policy_cost(indoor_masks, 2).
 policy_cost(vaccination_and_masks, 5).
 
+% Risk multiplies the base reproduction estimate by policy-specific factors.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 risk_score(P, R) :-
   base_risk(Base),
   vaccination_factor(P, VF),
@@ -48,6 +53,7 @@ status(P, insufficient_control) :-
 status(P, acceptable_control) :-
   acceptable(P).
 
+% The recommendation is the only candidate below the outbreak threshold.
 recommended(vaccination_and_masks) :-
   acceptable(vaccination_and_masks),
   status(no_mandate, insufficient_control),

package/examples/equivalence-classes-overlap-implies-same-class.pl

@@ -1,5 +1,7 @@
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(sameClassBecauseOfSharedMember, 3).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % Equivalence-classes example adapted from Eyeling
 % equivalence-classes-overlap-implies-same-class.n3.
 % The finite class membership facts represent the equivalence closure generated
@@ -9,6 +11,7 @@ classMember(class_abc, a).
 classMember(class_abc, b).
 classMember(class_abc, c).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 inClassOf(U, X) :-
   classMember(Class, U),
   classMember(Class, X).

package/examples/eulerian-path.pl

@@ -1,11 +1,14 @@
 % Eyelet-inspired Eulerian path example using findall/3 and sort/2.
 % The graph is undirected; edges are represented by identifiers so each edge is used once.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(oddVertices, 2).
 materialize(path, 2).
 materialize(edgeCount, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Edge identifiers let the search remove each physical edge exactly once.
 edge(e12, v1, v2).
 edge(e13, v1, v3).
 edge(e15, v1, v5).
@@ -18,6 +21,7 @@ edge(e36, v3, v6).
 edge(e45, v4, v5).
 edge(e46, v4, v6).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 vertex(V) :- edge(_E, V, _U).
 vertex(V) :- edge(_E, _U, V).
 
@@ -31,6 +35,7 @@ select(Item, [Item | Rest], Rest).
 select(Item, [Head | Tail], [Head | Rest]) :-
   select(Item, Tail, Rest).
 
+% Eulerian paths start at an odd-degree vertex when exactly two exist.
 odd_degree(V) :-
   findall(E, incident(V, E), Edges),
   length(Edges, Degree),
@@ -60,6 +65,7 @@ eulerian_path(Path) :-
   dfs_euler(Start, [Start], Edges, ReversedPath),
   reverse(ReversedPath, Path).
 
+% Depth-first search consumes the remaining edge-id list one edge at a time.
 dfs_euler(_Current, Path, [], Path).
 dfs_euler(Current, Visited, Remaining, Path) :-
   adjacent_by_edge(Current, Next, Edge),

package/examples/ev-range-worlds.pl

@@ -1,11 +1,13 @@
 % EYE-inspired electric-vehicle range worlds.
 % Four simple worlds estimate whether trips fit the available battery.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(safeInWorld, 2).
 materialize(riskyInWorld, 2).
 materialize(reason, 2).
 materialize(status, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 trip(city_errand).
 trip(winter_highway).
 trip(heavy_delivery).
@@ -17,6 +19,7 @@ trip_data(winter_highway, 260, 115, -5, 400, 60, 0.20).
 trip_data(heavy_delivery, 180, 80, 15, 700, 55, 0.22).
 trip_data(cold_commute, 120, 90, -8, 100, 35, 0.19).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 speed_factor(T, 1.20) :- trip_data(T, _, S, _, _, _, _), gt(S, 100).
 speed_factor(T, 1.00) :- trip_data(T, _, S, _, _, _, _), le(S, 100).
 

package/examples/exact-cover-sudoku.pl

@@ -5,10 +5,13 @@
 % The solver then chooses one candidate per row and checks the exact-cover
 % constraints for all columns and 3x3 boxes.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(status, 2).
 materialize(solution, 2).
 materialize(firstRow, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 cover9(Cells) :-
   sort(Cells, [1, 2, 3, 4, 5, 6, 7, 8, 9]).
 

package/examples/existential-rule.pl

@@ -1,5 +1,7 @@
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(is, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % Existential-rule example adapted from Eyeling existential-rule.n3.
 % Eyeling creates blank-node witnesses.  eyelang has Herbrand terms only, so the
 % witness is represented explicitly by a deterministic Skolem-style term.
@@ -10,6 +12,7 @@ type(plato, human).
 witness(socrates, sk_0).
 witness(plato, sk_1).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 is(Person, Witness) :-
   type(Person, human),
   witness(Person, Witness).

package/examples/exoplanet-validation-worlds.pl

@@ -3,12 +3,14 @@
 % Four simplified worlds classify candidate transit signals using either Bayes,
 % sensitivity-only reasoning, a heuristic threshold, or a stricter Bayesian rule.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(ppvPlanetGivenDetection, 2).
 materialize(confirmsInWorld, 2).
 materialize(rejectsInWorld, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 candidate(rare_wide_orbit, 0.001, 0.99, 0.99).
 candidate(mstar_short_period, 0.20, 0.99, 0.99).
 candidate(common_hot_neptune_good, 0.25, 0.95, 0.97).
@@ -19,6 +21,7 @@ world(w1, sensitivity_only_naive).
 world(w2, occurrence_sensitivity_specificity_heuristic).
 world(w3, cautious_bayes_threshold).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 ppv_planet(Candidate, PPV) :-
   candidate(Candidate, Occurrence, Sensitivity, Specificity),
   mul(Sensitivity, Occurrence, Numerator),

package/examples/expression-eval.pl

@@ -1,7 +1,10 @@
 % Tiny expression evaluator adapted from Eyeling's expression-eval.n3 example.
 % Data: (2 * 3) + (10 - 4) = 12.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(result, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Leaves are number/2 facts; internal nodes name an operator and two children.
 number(n2, 2).
 number(n3, 3).
 number(n10, 10).
@@ -12,6 +15,8 @@ expr(eSub, sub, n10, n4).
 expr(eAdd, add, eMul, eSub).
 root(eAdd).
 
+% Evaluation is recursive over the expression tree.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 value(Node, Value) :-
   number(Node, Value).
 

package/examples/family-cousins.pl

@@ -1,9 +1,11 @@
 % Memoize scoped family projection and recursive labels; cousin derivation asks
 % for the same generation and branch facts many times.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(generation, 2).
 materialize(branch, 2).
 materialize(cousin, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 memoize(family_statement, 3).
 memoize(generation, 2).
 memoize(branch, 2).
@@ -30,6 +32,7 @@ family_graph(familyGraph, (
   seedBranch(grace, c)
 )).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 family_statement(S, P, O) :- family_graph(familyGraph, Formula), formula_binary(Formula, S, P, O).
 
 parent(Parent, Child) :- family_statement(Parent, parent, Child).

package/examples/fastpow.pl

@@ -1,12 +1,16 @@
 % Fast exponentiation examples adapted from Eyeling fastpow.n3.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(pow, 2).
 materialize(powSlow, 2).
 materialize(powMod1e6, 2).
 materialize(tower, 2).
 materialize(towerMod1e6, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% pow/3 uses exponentiation by squaring.
 pow(_Base, 0, 1).
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 pow(Base, Exp, Value) :-
   gt(Exp, 0),
   mod(Exp, 2, 0),
@@ -20,6 +24,7 @@ pow(Base, Exp, Value) :-
   pow(Base, EvenExp, EvenValue),
   mul(Base, EvenValue, Value).
 
+% pow_mod/4 applies the modulus at each multiplication to keep values small.
 pow_mod(_Base, 0, _Mod, 1).
 pow_mod(Base, Exp, Mod, Value) :-
   gt(Exp, 0),

package/examples/fft8-numeric.pl

@@ -1,9 +1,12 @@
 % Adapted from Eyeling's fft8-numeric.n3.
 % A radix-2 FFT over explicit complex pairs c(Re, Im).
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(fft, 2).
 materialize(dcComponent, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Twiddle factors are encoded as complex pairs c(Real, Imag).
 w8(0, c(1.0, 0.0)).
 w8(1, c(0.7071067811865476, -0.7071067811865476)).
 w8(2, c(0.0, -1.0)).
@@ -13,6 +16,8 @@ w8(5, c(-0.7071067811865476, 0.7071067811865476)).
 w8(6, c(0.0, 1.0)).
 w8(7, c(0.7071067811865476, 0.7071067811865476)).
 
+% Complex arithmetic is expressed through ordinary numeric built-ins.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 c_add(c(AR, AI), c(BR, BI), c(CR, CI)) :-
   add(AR, BR, CR),
   add(AI, BI, CI).
@@ -47,6 +52,7 @@ fft4([X0, X1, X2, X3], [Y0, Y1, Y2, Y3]) :-
   c_sub(E0, O0, Y2),
   c_sub(E1, T1, Y3).
 
+% Split even/odd samples, transform halves, then combine with W8 factors.
 fft8([X0, X1, X2, X3, X4, X5, X6, X7], [Y0, Y1, Y2, Y3, Y4, Y5, Y6, Y7]) :-
   fft4([X0, X2, X4, X6], [E0, E1, E2, E3]),
   fft4([X1, X3, X5, X7], [O0, O1, O2, O3]),

package/examples/fibonacci.pl

@@ -1,7 +1,9 @@
 % Memoize the fast-doubling helper: several requested Fibonacci numbers reuse
 % the same half-size subproblems.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(fibonacci, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 memoize(fib_pair, 3).
 
 % BigInt Fibonacci via fast doubling, implemented in Prolog using generic
@@ -14,6 +16,7 @@ fib_case(100).
 fib_case(1000).
 fib_case(10000).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 fib(N, Value) :- fib_pair(N, Value, _Next).
 
 fib_pair(0, 0, 1).

package/examples/field-nitrogen-balance.pl

@@ -2,6 +2,7 @@
 % Fields are classified from soil N, fertilizer N, losses, and crop demand.
 
 % field(Field, SoilN, FertilizerN, LossFraction, CropDemandN).
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(availableN_kg_ha, 2).
 materialize(deficitN_kg_ha, 2).
 materialize(surplusN_kg_ha, 2).
@@ -10,11 +11,13 @@ materialize(status, 2).
 materialize(highestLeachingRisk, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 field(low_input, 25, 40, 0.10, 110).
 field(balanced_loam, 45, 80, 0.12, 110).
 field(sandy_high, 30, 150, 0.35, 105).
 field(clay_surplus, 70, 90, 0.08, 120).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 total_n(F, Total) :-
   field(F, Soil, Fert, _, _),
   add(Soil, Fert, Total).

package/examples/flandor.pl

@@ -3,6 +3,7 @@
 % the neutral insight, policy envelope, authorization, package choice, and checks
 % as materialized relation output.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(caseName, 2).
 materialize(regionName, 2).
 materialize(metric, 2).
@@ -42,6 +43,8 @@ materialize(surveillanceReuseProhibited, 2).
 materialize(filesWrittenExpected, 2).
 materialize(lowestCostEligiblePackageChosen, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Case metadata describes the request, audit window, and expected file writes.
 case_name(case, "flandor").
 question(case, "Is the Flemish Economic Resilience Board allowed to use a neutral macro-economic insight for regional stabilization, and if so which package should it activate for Flanders?").
 expectedFilesWritten(case, 6).
@@ -60,6 +63,7 @@ aggregationLevel(signals, "regional_cluster").
 containsFirmNames(signals, false).
 containsPayrollRows(signals, false).
 
+% Signals are intentionally aggregated: no firm names or payroll rows are present.
 industrialCluster(clusterAntwerp).
 clusterName(clusterAntwerp, "Antwerp chemicals").
 exportOrdersIndex(clusterAntwerp, 84).
@@ -76,6 +80,7 @@ renewableCurtailmentMWh(grid, 240).
 maxMEUR(budget, 140).
 windowName(budget, "Q2 resilience window").
 
+% Candidate packages expose cost and which active needs they cover.
 policyPackage(pkgTrainingOnly).
 packageId(pkgTrainingOnly, "pkg:TRAIN_070").
 packageName(pkgTrainingOnly, "Flanders Skills Sprint").
@@ -142,6 +147,7 @@ hmacVerificationMode(signature, trustedPrecomputedInput).
 
 reason_value(reasonText, "Secure aggregates from Flanders indicate simultaneous export weakness, technical labour scarcity, and grid congestion. A neutral macro insight is scoped to the economic-resilience board for one budget window only, enabling a temporary package without exposing firm-level books.").
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 caseName(Case, Name) :- case_name(Case, Name).
 regionName(Region, Name) :- region_name(Region, Name).
 metric(Insight, Metric) :- insight_metric(Insight, Metric).
@@ -187,6 +193,7 @@ scope_complete(check) :-
   scopeEvent(macroInsight, _Event),
   expiresAt(macroInsight, _Expiry).
 
+% Authorization combines policy scope, envelope timing, and use permission.
 authorization_allowed(check) :-
   permission(policy, odrlUse, macroInsight, "regional_stabilization"),
   boardAuthAt(case, AuthAt),
@@ -195,6 +202,7 @@ authorization_allowed(check) :-
 
 decision(decision, "Allowed", macroInsight) :- authorization_allowed(check).
 
+% An eligible package must cover every active need and fit under the budget cap.
 eligible_package(Pkg) :-
   needs_retooling_pulse(case),
   maxMEUR(budget, Max),
@@ -210,6 +218,7 @@ lower_cost_eligible_package(Cost) :-
   costMEUR(Other, OtherCost),
   lt(OtherCost, Cost).
 
+% The recommendation is the lowest-cost eligible package.
 recommended_package(case, Pkg) :-
   eligible_package(Pkg),
   costMEUR(Pkg, Cost),

package/examples/floating-point.pl

@@ -1,12 +1,16 @@
 % Floating-point arithmetic and comparisons.
 % Integer-only operands continue to use arbitrary-size integer arithmetic.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(value, 2).
 materialize(than, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Floating-point constants can be mixed with integer constants in built-ins.
 sample(roomC, 21.5).
 sample(targetC, 19.25).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 value(sum, X) :- add(1.5, 2.25, X).
 value(difference, X) :- sub(10.0, 3.125, X).
 value(product, X) :- mul(2.5, 4.0, X).
@@ -15,4 +19,5 @@ value(sqrtByPower, X) :- pow(9.0, 0.5, X).
 value(mathSum, X) :- add(0.125, 0.875, X).
 value(mathProduct, X) :- mul(6.0, 0.5, X).
 than(warmer, targetC) :- sample(roomC, R), sample(targetC, T), gt(R, T).
+% Boolean-like conclusions remain ordinary atoms.
 value(comfortable, true) :- sample(roomC, R), ge(R, 21.0), le(R, 22.0).

package/examples/four-color-map.pl

@@ -4,10 +4,12 @@
 % four colours. This eyelang version keeps the same map/assignment shape and adds
 % a rule-level validation layer that rejects equal colours across borders.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(color, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 country(belgium). country(netherlands). country(luxemburg). country(france).
 country(germany). country(italy). country(denmark). country(ireland).
 country(greece). country(spain). country(portugal). country(austria).
@@ -36,6 +38,7 @@ border(estonia, latvia).
 border(latvia, lithuania).
 border(bulgaria, romania).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 adjacent(A, B) :- border(A, B).
 adjacent(A, B) :- border(B, A).
 

package/examples/fundamental-theorem-arithmetic.pl

@@ -2,6 +2,7 @@
 % Compute a prime factorization by repeated smallest-divisor decomposition,
 % then check product reconstruction and primality of the distinct factors.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(n, 2).
 materialize(factorsSmallest, 2).
 materialize(factorsLargest, 2).
@@ -12,10 +13,12 @@ materialize(distinctPrimeCount, 2).
 materialize(smallestPrimeFactor, 2).
 materialize(largestPrimeFactor, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 case(fta, 202692987).
 expected_factors(fta, [3, 3, 7, 829, 3881]).
 
 % A divides B in positive integers.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 divides(A, B) :-
   gt(A, 0),
   gt(B, 0),

package/examples/gcd-bezout-identity.pl

@@ -4,11 +4,13 @@
 % Each case derives gcd(a,b), coefficients s,t, and validation checks for
 % a*s + b*t = gcd(a,b) and divisibility.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(gcd, 2).
 materialize(bezoutCoefficients, 2).
 materialize(check, 2).
 materialize(status, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 case(c1, 48, 18).
 case(c2, 101, 462).
 case(c3, 0, 5).
@@ -16,6 +18,7 @@ case(c4, 270, 192).
 case(c5, -27, 36).
 case(c6, 123456, 7890).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 answer(Case, Gcd, S, T) :-
   case(Case, A, B),
   extended_gcd(A, B, Gcd, S, T).

package/examples/gd-step-certified.pl

@@ -1,5 +1,6 @@
 % Memoize interval computations reused across width, midpoint, gradient, step,
 % objective, and contraction report relations.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(eta, 2).
 materialize(etaLeHalf, 2).
 materialize(xBounds, 2).
@@ -10,6 +11,7 @@ materialize(stepBounds, 2).
 materialize(objectiveBounds, 2).
 materialize(widthContractsAt, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 memoize(x_bounds, 3).
 memoize(width, 2).
 memoize(g_bounds, 3).
@@ -23,6 +25,7 @@ memoize(f_upper, 2).
 
 max_k(10).
 target(1.0).
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 eta(Eta) :- div(1.0, 5, Eta).
 x_bounds(0, 0.0, 2.0).
 

package/examples/gdpr-compliance.pl

@@ -1,8 +1,11 @@
 % GDPR-style compliance check: purpose, basis, minimisation, safeguards, and export.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% case_alpha is intended to pass; case_beta is intentionally incomplete.
 processing(case_alpha).
 processing(case_beta).
 
@@ -25,6 +28,8 @@ safeguard(case_beta, encryption).
 third_country_transfer(case_beta).
 adequacy_decision(case_alpha).
 
+% Compliance is decomposed into reusable checks so reasons can be reported.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 has_required_basis(Case) :- legal_basis(Case, explicit_consent).
 has_required_basis(Case) :- legal_basis(Case, medical_care).
 
@@ -43,6 +48,7 @@ compliant(Case) :-
   has_health_safeguards(Case),
   transfer_ok(Case).
 
+% Individual failure rules explain why a case is noncompliant.
 noncompliance_reason(Case, missing_legal_basis) :-
   processing(Case),
   not(has_required_basis(Case)).

package/examples/goldbach-1000.pl

@@ -1,8 +1,10 @@
 % Goldbach pairs up to 1000.
 % Prime numbers are input data; the rule below derives all Goldbach pairs.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(isPrime, 2).
 materialize(goldbachOk, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 prime(2).
 prime(3).
 prime(5).
@@ -172,6 +174,7 @@ prime(983).
 prime(991).
 prime(997).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 even_between_4_1000(N) :- between(4, 1000, N), mod(N, 2, 0).
 
 isPrime(N, true) :-

package/examples/good-cobbler.pl

@@ -3,9 +3,12 @@
 % The Eyeling result is a quoted assertion saying that joe is a good Cobbler.
 % Here the quoted assertion is represented as an eyelang term.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(is, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 assertedIs(joe, good(cobbler)).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 is(test, is(X, good(Y))) :-
   assertedIs(X, good(Y)).

package/examples/gps.pl

@@ -1,5 +1,6 @@
 % Memoize route paths because the same candidate routes are checked repeatedly
 % for explanation and verification relations.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(recommendedRoute, 2).
 materialize(outcome, 2).
 materialize(statement, 3).
@@ -12,6 +13,7 @@ materialize(comfort, 2).
 materialize(selectedRoute, 2).
 materialize(comparison, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 memoize(path, 7).
 memoize(traveller_path, 6).
 
@@ -35,6 +37,7 @@ map_graph(mapBE, (
   gps_description(mapBE, description(location(S, brugge), true, location(S, oostende), drive_brugge_oostende, 900.0, 0.004, 0.98, 1.0))
 )).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 case_statement(S, P, O) :-
   case_graph(caseGraph, Formula),
   formula_binary(Formula, S, P, O).

package/examples/graph-reachability.pl

@@ -3,9 +3,11 @@
 % The original uses Prolog negation and member/2 to avoid revisiting nodes.
 % eyelang expresses the same finite search with not(member(...)).
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(reachable, 2).
 materialize(not_reachable, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 edge(a, b).
 edge(a, c).
 edge(b, d).
@@ -15,6 +17,7 @@ edge(e, f).
 edge(f, g).
 
 reachable(Node, Node, _Visited).
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 reachable(Start, Goal, Visited) :-
   edge(Start, Next),
   not(member(Next, Visited)),

package/examples/gray-code-counter.pl

@@ -1,8 +1,11 @@
 % Gray-code counter adapted from Eyeling gray-code-counter.n3 and the
 % Clause and Effect example referenced there.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(isgcc, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Boolean gates are truth tables; the circuit rules compose them.
 and(0, 0, 0). and(0, 1, 0). and(1, 0, 0). and(1, 1, 1).
 or(0, 0, 0).  or(0, 1, 1).  or(1, 0, 1).  or(1, 1, 1).
 inv(0, 1). inv(1, 0).
@@ -10,6 +13,7 @@ inv(0, 1). inv(1, 0).
 dff(D, 0, Q, Q).
 dff(D, 1, _Q, D).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 neta(A, B, Q) :-
   and(A, B, T1),
   inv(A, NA),
@@ -26,6 +30,7 @@ netb(A, B, C, Q1, Q2) :-
   or(T1, T2, Q1),
   or(T2, T3, Q2).
 
+% One clock step computes D inputs, then updates the three flip-flops.
 gcc(C, [Qa, Qb, Qc], [Za, Zb, Zc]) :-
   netb(Qa, Qb, Qc, D1, D2),
   neta(Qa, Qb, D3),
@@ -33,6 +38,7 @@ gcc(C, [Qa, Qb, Qc], [Za, Zb, Zc]) :-
   dff(D2, C, Qb, Zb),
   dff(D3, C, Qc, Zc).
 
+% testgcc/3 runs the circuit over a list of clock inputs.
 testgcc([], _State, []).
 testgcc([C|Cs], State, [Next|Rest]) :-
   gcc(C, State, Next),

package/examples/greatest-lower-bound-uniqueness.pl

@@ -1,5 +1,7 @@
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(sameGreatestLowerBound, 4).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % Greatest-lower-bound uniqueness example adapted from Eyeling
 % greatest-lower-bound-uniqueness.n3.
 % If M and N are both greatest lower bounds of A and B, each is below the other;
@@ -8,6 +10,7 @@ materialize(sameGreatestLowerBound, 4).
 glbOf(g1, a, b).
 glbOf(g2, a, b).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 lowerBoundOf(M, A, B) :- glbOf(M, A, B).
 
 leq(L, M) :-

package/examples/group-inverse-uniqueness.pl

@@ -3,13 +3,16 @@
 % The output mirrors the Eyeling golden result shape:
 % sameInverse(x, i, j) and sameInverse(x, j, i).
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(sameInverse, 3).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 element(e).
 element(x).
 element(i).
 element(j).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 op(e, X, X) :- element(X).
 op(X, e, X) :- element(X).
 op(i, x, e).