eyelang 1.5.3 → 1.5.4

package/examples/hamiltonian-cycle.pl

@@ -5,11 +5,13 @@
 % cycle directions are still distinct, so the count is for cycles from a fixed
 % start in traversal order.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(status, 2).
 materialize(witness, 2).
 materialize(vertexCount, 2).
 materialize(cycleCountFromA, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 edge(a, b).
 edge(a, f).
 edge(a, g).
@@ -28,6 +30,7 @@ edge(e, f).
 edge(f, g).
 edge(g, h).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 adjacent(X, Y) :- edge(X, Y).
 adjacent(X, Y) :- edge(Y, X).
 

package/examples/hamiltonian-path.pl

@@ -4,9 +4,11 @@
 % vertex set directly and derives every path that visits each vertex exactly
 % once.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(hasHamiltonianPath, 2).
 materialize(hamiltonianPath, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 memoize(adjacent, 2).
 
 edge(v1, v2).
@@ -21,6 +23,7 @@ edge(v3, v6).
 edge(v4, v5).
 edge(v4, v6).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 adjacent(V, U) :- edge(V, U).
 adjacent(V, U) :- edge(U, V).
 

package/examples/hamming-code.pl

@@ -3,6 +3,7 @@
 % The received word has one corrupted bit. Syndrome bits identify the bad
 % position, then the corrected codeword and decoded payload are derived.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(syndrome, 2).
 materialize(errorBit, 2).
 materialize(correctedCodeword, 2).
@@ -10,6 +11,7 @@ materialize(decodedPayload, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 received_bit(packet1, 1, 1).
 received_bit(packet1, 2, 0).
 received_bit(packet1, 3, 1).
@@ -21,6 +23,7 @@ received_bit(packet1, 7, 0).
 flip(0, 1).
 flip(1, 0).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 parity4(A, B, C, D, Parity) :-
   add(A, B, AB),
   add(AB, C, ABC),

package/examples/hanoi.pl

@@ -1,11 +1,14 @@
 % Towers of Hanoi adapted from Eyeling hanoi.n3.
 % Output is the complete list of moves for size 3.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(answer, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 memoize(hanoi, 5).
 
 hanoi(0, _From, _To, _Via, []).
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 hanoi(N, From, To, Via, Moves) :-
   gt(N, 0),
   sub(N, 1, N1),

package/examples/heat-loss.pl

@@ -2,18 +2,21 @@
 %
 % Thermal resistance is L/(k*A), and heat loss is DeltaT/R.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(type, 2).
 materialize(temperatureDifference_K, 2).
 materialize(thermalResistance_K_W, 2).
 materialize(heatLoss_W, 2).
 materialize(status, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 wall(wall1, conductivity_W_mK, 0.8).
 wall(wall1, area_m2, 12.0).
 wall(wall1, thickness_m, 0.2).
 wall(wall1, indoor_C, 21.0).
 wall(wall1, outdoor_C, -4.0).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 temperature_difference(Wall, DeltaT) :-
   wall(Wall, indoor_C, Indoor),
   wall(Wall, outdoor_C, Outdoor),

package/examples/heron-theorem.pl

@@ -1,18 +1,23 @@
 % Heron's theorem: area = sqrt(s(s-a)(s-b)(s-c)).
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(semiperimeter, 2).
 materialize(heronProduct, 2).
 materialize(area, 2).
 materialize(status, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% 13-14-15 is a classic integer-sided triangle with area 84.
 triangle(field_plot, 13, 14, 15).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 semiperimeter(Triangle, S) :-
   triangle(Triangle, A, B, C),
   add(A, B, AB),
   add(AB, C, Sum),
   div(Sum, 2, S).
 
+% Area is obtained by taking the square root of this Heron product.
 heron_product(Triangle, Product) :-
   triangle(Triangle, A, B, C),
   semiperimeter(Triangle, S),

package/examples/ideal-gas-law.pl

@@ -3,14 +3,17 @@
 % A simple gas cell uses P*V = n*R*T.  The constants are chosen so that the
 % computed pressure is exactly near one atmosphere in this small example.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(pressure_Pa, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 gas_cell(cell1, 1.0, 8.0, 300.0, 0.024).
 pressure_limit(cell1, low_Pa, 95000.0).
 pressure_limit(cell1, high_Pa, 105000.0).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 pressure(Cell, Pressure) :-
   gas_cell(Cell, Moles, GasConstant, Temperature, Volume),
   mul(Moles, GasConstant, NR),

package/examples/illegitimate-reasoning.pl

@@ -7,6 +7,7 @@
 
 % Affirming the consequent:
 %   If it rained, the street is wet. The street is wet. Therefore it rained.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(type, 2).
 materialize(fallacy, 2).
 materialize(conclusion, 2).
@@ -15,6 +16,7 @@ materialize(sampleSize, 2).
 materialize(requiredSampleSize, 2).
 materialize(omittedAlternative, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 argument(arg_affirming_consequent).
 implication(arg_affirming_consequent, rain, street_wet).
 observed(arg_affirming_consequent, street_wet).
@@ -47,6 +49,7 @@ implication(arg_modus_ponens, subscription_paid, access_allowed).
 observed(arg_modus_ponens, subscription_paid).
 concludes(arg_modus_ponens, access_allowed).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 fallacy(A, affirming_consequent) :-
   argument(A),
   implication(A, Antecedent, Consequent),

package/examples/kaprekar.pl

@@ -5,12 +5,15 @@
 % until Kaprekar's constant 6174 is reached.  The sample set is small so the
 % example remains a millisecond-scale demo in the normal test suite.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(constant, 2).
 materialize(kaprekarSteps, 2).
 materialize(reachesConstant, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 memoize(kaprekar, 3).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 recursion_count(N, Count) :-
   kaprekar_steps(N, Count).
 

package/examples/law-of-cosines.pl

@@ -1,12 +1,17 @@
 % Law of cosines: c^2 = a^2 + b^2 - 2ab cos(C).
 % The example uses a 60-degree included angle, so cos(C) is represented as 0.5.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(sideCSquared, 2).
 materialize(sideC, 2).
 materialize(status, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Stored tuple is triangle(Name, sideA, sideB, cosIncludedAngle).
 triangle(tri60, 7, 9, 0.5).
 
+% Compute c^2 first so both squared and square-rooted outputs can be shown.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 side_c_squared(Triangle, C2) :-
   triangle(Triangle, A, B, CosC),
   mul(A, A, A2),

package/examples/least-squares-regression.pl

@@ -3,16 +3,19 @@
 % The rules reduce a list of points to sufficient statistics, then derive the
 % fitted slope, intercept, and coefficient of determination R^2.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(slope, 2).
 materialize(intercept, 2).
 materialize(rSquared, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 dataset(regression1, [point(1.0, 2.0), point(2.0, 3.0), point(3.0, 5.0), point(4.0, 4.0)]).
 threshold(regression1, minimum_r_squared, 0.60).
 
 stats([], 0.0, 0.0, 0.0, 0.0, 0.0, 0.0).
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 stats([point(X, Y)|Rest], N, SumX, SumY, SumXX, SumXY, SumYY) :-
   stats(Rest, N0, SumX0, SumY0, SumXX0, SumXY0, SumYY0),
   add(N0, 1.0, N),

package/examples/list-collection.pl

@@ -1,14 +1,19 @@
 % List collections inspired by the Eyeling collection example.
 % Demonstrates list literals, member/2, length/2, append/3, and [Head|Tail].
+% Each materialized relation demonstrates one list operation.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(length, 2).
 materialize(member, 2).
 materialize(append, 2).
 materialize(head, 2).
 materialize(tail, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Lists are first-class terms in facts and rule heads/bodies.
 collection(numbers, [1, 2, 3]).
 collection(letters, [a, b]).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 length(numbers, N) :-
   collection(numbers, List),
   length(List, N).

package/examples/lldm.pl

@@ -4,6 +4,7 @@
 % the default relation materialization stays concise.  The visible output is
 % the alarm plus the small set of relations explaining why the alarm fired.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(type, 2).
 materialize(lld_left_length_cm, 2).
 materialize(lld_right_length_cm, 2).
@@ -11,6 +12,7 @@ materialize(lld_discrepancy_cm, 2).
 materialize(lld_threshold_cm, 2).
 materialize(lld_reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 measurement(meas47).
 
 % measured landmark coordinates, in centimetres
@@ -27,6 +29,7 @@ val(meas47, p4yCm, 28.5).
 threshold(meas47, lld_alarm_threshold_cm, 1.25).
 
 % geometric intermediate values
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 val(M, dx12Cm, Z) :- measurement(M), val(M, p1xCm, X), val(M, p2xCm, Y), sub(X, Y, Z).
 val(M, dx51Cm, Z) :- measurement(M), val(M, p5xCm, X), val(M, p1xCm, Y), sub(X, Y, Z).
 val(M, dx53Cm, Z) :- measurement(M), val(M, p5xCm, X), val(M, p3xCm, Y), sub(X, Y, Z).

package/examples/manufacturing-quality-control.pl

@@ -3,10 +3,12 @@
 % The rules compute process capability indices from measurement summaries and
 % classify production lines using a practical Cpk threshold.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(cpk, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 run(line7_shift_a).
 run(line8_shift_b).
 
@@ -22,6 +24,7 @@ summary(line8_shift_b, sigma_mm, 0.02).
 
 capability_threshold(cpk, 1.33).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 upper_margin_mm(Run, Margin) :-
   spec(Run, upper_mm, Upper),
   summary(Run, mean_mm, Mean),

package/examples/matrix.pl

@@ -7,10 +7,13 @@
 
 % --- small list helpers -----------------------------------------------------
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(result, 2).
 materialize(checksConsistentWithTreallaReference, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 nth0(0, [H|_T], H).
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 nth0(N, [_H|T], V) :-
   gt(N, 0),
   sub(N, 1, N1),

package/examples/microgrid-dispatch.pl

@@ -3,6 +3,7 @@
 % The rules compute renewable supply, reserve-aware battery dispatch, remaining
 % grid import, and a concise feasibility report for a campus microgrid interval.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(renewablePower_kW, 2).
 materialize(batteryDispatch_kW, 2).
 materialize(gridImport_kW, 2).
@@ -10,6 +11,7 @@ materialize(reserveAfterDispatch_kW, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 site(campus_interval_17).
 
 load_kW(campus_interval_17, 620.0).
@@ -19,6 +21,7 @@ battery_max_discharge_kW(campus_interval_17, 320.0).
 required_battery_reserve_kW(campus_interval_17, 80.0).
 grid_contract_limit_kW(campus_interval_17, 150.0).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 renewable_kW(Site, Renewable) :-
   solar_kW(Site, Solar),
   wind_kW(Site, Wind),

package/examples/monkey-bananas.pl

@@ -5,11 +5,14 @@
 % has_bananas].  The selected output searches bounded move lists and derives successful
 % plans.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(plan, 2).
 materialize(solved, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 memoize(reachable, 3).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 plan(Moves) :-
   candidate_plan(Moves),
   initial_state(I),

package/examples/n-queens.pl

@@ -10,9 +10,12 @@
 % Row - Q.  Rejecting repeats in those two lists enforces the remaining
 % N-queens constraints declaratively, without cut or destructive update.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(solution, 2).
 materialize(solved, 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.
 queens(N, Qs) :-
   n_queens(N, Qs).
 

package/examples/network-sla.pl

@@ -3,11 +3,13 @@
 % The path latency is the sum of link delays plus jitter. The path is compliant
 % when the resulting end-to-end latency stays below the SLA limit.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(endToEndLatency_ms, 2).
 materialize(slaLimit_ms, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 path(edge_path, [link_a, link_b, link_c]).
 link_latency(link_a, 12.0).
 link_latency(link_b, 18.0).
@@ -16,6 +18,7 @@ jitter(edge_path, 8.0).
 sla(edge_path, maximum_latency_ms, 50.0).
 
 latency_sum([], 0.0).
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 latency_sum([Link|Links], Total) :-
   link_latency(Link, LinkLatency),
   latency_sum(Links, Rest),

package/examples/newton-raphson.pl

@@ -1,12 +1,15 @@
 % Newton-Raphson root finding, adapted from Eyelet input/newton-raphson.pl.
 % The selected roots match Eyelet output-swipl/newton-raphson.pl.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(findRoot, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 want_root([1, 1.0, 1.0e-15]).
 want_root([2, 2.0, 1.0e-15]).
 want_root([3, 3.0, 1.0e-15]).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 findRoot(Input, Root) :-
   want_root(Input),
   find_root(Input, Root).

package/examples/nixon-diamond.pl

@@ -3,13 +3,16 @@
 % a subject with both defaults is reported as conflicted rather than forced to
 % choose one extension.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(defaultSupports, 2).
 materialize(conflict, 2).
 materialize(status, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 kind(nixon, quaker).
 kind(nixon, republican).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 supports_default(Person, pacifist) :-
   kind(Person, quaker).
 

package/examples/odrl-dpv-healthcare-risk-ranked.pl

@@ -2,6 +2,7 @@
 % odrl-dpv-healthcare-risk-ranked.n3.
 % The agreement policy and mitigation suggestions are formula-valued terms.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(policyGraph, 2).
 materialize(contains, 2).
 materialize(dpv_hasRisk, 2).
@@ -20,6 +21,7 @@ materialize(suggestAddGraph, 2).
 materialize(firstRisk, 2).
 materialize(retentionRiskScore, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 party(hospital).
 party(researchUnit).
 party(pharmaPartner).
@@ -110,6 +112,7 @@ policy_graph(policyGraphHC1, (
   clause(permRetention10y, clauseH4)
 )).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 policy_statement(GraphName, Subject, Predicate, Object) :-
   policy_graph(GraphName, Formula),
   formula_binary(Formula, Subject, Predicate, Object).

package/examples/odrl-dpv-risk-ranked.pl

@@ -5,6 +5,7 @@
 % reasoning, and materializes the derived DPV risks as relation output.
 
 % Consumer profile and needs.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(dct_title, 2).
 materialize(dpv_hasRisk, 2).
 materialize(type, 2).
@@ -31,6 +32,7 @@ materialize(dpv_mitigatesRisk, 2).
 materialize(clauseId, 2).
 materialize(text, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 consumer(consumerExample).
 title(consumerExample, "Example consumer profile").
 has_need(consumerExample, need_DataCannotBeRemoved).
@@ -94,6 +96,7 @@ policy_graph(policyGraph1, (
   clause(prohibitExportData, clauseC4)
 )).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 policy_statement(Subject, Predicate, Object) :-
   policy_graph(_Graph, Formula),
   formula_binary(Formula, Subject, Predicate, Object).

package/examples/orbital-transfer-design.pl

@@ -4,6 +4,7 @@
 % mission constraints. Distances are in kilometres, speeds in kilometres per
 % second, and time in days.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(transferSemiMajorAxis_km, 2).
 materialize(departureDeltaV_km_s, 2).
 materialize(arrivalDeltaV_km_s, 2).
@@ -12,6 +13,7 @@ materialize(transferTime_days, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 mission(mars_hohmann, centralBodyMu_km3_s2, 132712440018.0).
 mission(mars_hohmann, departureOrbitRadius_km, 149597870.7).
 mission(mars_hohmann, arrivalOrbitRadius_km, 227939200.0).
@@ -19,6 +21,7 @@ mission(mars_hohmann, deltaVBudget_km_s, 6.0).
 mission(mars_hohmann, pi, 3.141592653589793).
 mission(mars_hohmann, secondsPerDay, 86400.0).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 semi_major_axis(Mission, Axis) :-
   mission(Mission, departureOrbitRadius_km, R1),
   mission(Mission, arrivalOrbitRadius_km, R2),

package/examples/path-discovery.pl

@@ -1,9 +1,12 @@
 % Generic path discovery over the air-routes graph.
 % Change or add route_request(FromLabel, ToLabel, MaxStopOvers) to answer other routes.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(airroute, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 route_request("Ostend-Bruges International Airport", "Václav Havel Airport Prague", 2).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 airroute(discovered, RouteText) :-
   route_request(From, To, MaxStopOvers),
   airport(Source, From),

package/examples/peano-arithmetic.pl

@@ -3,9 +3,12 @@
 % The EYE example defines add, multiply and factorial over Peano numerals.
 % Its selected output computes (1 * 2 + 3)! and emits the factorial of 5.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(factorial, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 peano_add(A, 0, A).
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 peano_add(A, s(B), s(C)) :-
   peano_add(A, B, C).
 

package/examples/peasant.pl

@@ -1,9 +1,12 @@
 % Peasant multiplication and exponentiation cases, adapted from Eyelet
 % input/peasant.pl.  The selected answers match Eyelet output-swipl/peasant.pl.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(prod, 2).
 materialize(pow, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Inputs are explicit so the example does not enumerate an unbounded domain.
 want_prod([3, 0]).
 want_prod([5, 6]).
 want_prod([238, 13]).
@@ -16,6 +19,8 @@ want_pow([5, 6]).
 want_pow([238, 13]).
 want_pow([8367238, 2713]).
 
+% The arithmetic itself is delegated to the native numeric built-ins.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 prod([A, B], C) :-
   want_prod([A, B]),
   mul(A, B, C).

package/examples/pendulum-period.pl

@@ -3,17 +3,20 @@
 % For small oscillations, T = 2*pi*sqrt(length / gravity).  Gravity is chosen
 % as pi^2 m/s^2 so a one-meter pendulum has a period of two seconds.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(period_s, 2).
 materialize(periodError_s, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 constant(pi, 3.141592653589793).
 experiment(pendulum1, length_m, 1.0).
 experiment(pendulum1, gravity_m_s2, 9.869604401089358).
 limit(pendulum1, target_period_s, 2.0).
 limit(pendulum1, tolerance_s, 0.01).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 period(Experiment, Period) :-
   experiment(Experiment, length_m, Length),
   experiment(Experiment, gravity_m_s2, Gravity),

package/examples/polynomial.pl

@@ -6,12 +6,14 @@
 % searching a finite complex-integer candidate grid.  The two cases below are
 % the same quartic polynomials used by the Eyelet source.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(polynomial, 2).
 materialize(root, 2).
 materialize(reconstructedPolynomial, 2).
 materialize(reconstructionMatches, 2).
 materialize(allRootsVerified, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 case(real_quartic).
 case(complex_quartic).
 
@@ -32,6 +34,7 @@ known_roots(complex_quartic, [[0, 1], [1, 1], [3, 2], [5, 1]]).
 
 c_zero([0, 0]).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 c_add([A, B], [C, D], [E, F]) :-
   add(A, C, E),
   add(B, D, F).

package/examples/project-portfolio-optimization.pl

@@ -5,6 +5,7 @@
 % accumulate, then use aggregate builtins to select useful optima without
 % building and sorting a large bag of candidate portfolios.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(bestPortfolio, 2).
 materialize(lowRiskTarget, 2).
 materialize(feasibleCount, 2).
@@ -12,6 +13,7 @@ materialize(projectCount, 2).
 materialize(totalAvailableValue, 2).
 materialize(note, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 budget(portfolio2026, 75).
 riskCap(portfolio2026, 28).
 targetValue(portfolio2026, 125).
@@ -31,6 +33,7 @@ allProjectData([
   p(security, 25, 16, 7)
 ]).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 project(Name, Value, Cost, Risk) :-
   allProjectData(Projects),
   member(p(Name, Value, Cost, Risk), Projects).

package/examples/proof-contrapositive.pl

@@ -3,13 +3,16 @@
 % The implication itself is represented as data with implies/2.  The proof
 % rule remains ordinary eyelang: if A implies B and B is false, then A is false.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(refutes, 2).
 materialize(method, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 implies(raining, wet_ground).
 false(wet_ground).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 false(A) :-
   implies(A, B),
   false(B).

package/examples/quadratic-formula.pl

@@ -3,12 +3,15 @@
 % Each equation is represented as a*x^2 + b*x + c = 0.  The example uses
 % eyelang arithmetic predicates to derive the discriminant and the two roots.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(discriminant, 2).
 materialize(root, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 equation(eq1, 1.0, -5.0, 6.0).
 equation(eq2, 2.0, -4.0, -6.0).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 discriminant(Case, D) :-
   equation(Case, A, B, C),
   pow(B, 2.0, B2),