eyelang 1.5.3 → 1.5.4

package/examples/context-association.pl

@@ -4,11 +4,13 @@
 % and its contents remain quoted formula data.  Nothing inside the three formulae
 % is asserted globally unless a rule explicitly projects it.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(log_nameOf, 2).
 materialize(dataGraph, 2).
 materialize(signatureGraph, 2).
 materialize(metadataGraph, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 log_nameOf(skolem_g0, foaf_name(bob, "Bob")).
 
 log_nameOf(skolem_g1, (
@@ -36,6 +38,7 @@ log_nameOf(g3, (
 
 % A tiny projection shows how a program can inspect a quoted context without
 % making the entire context globally true.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 context_statement(Context, Subject, Predicate, Object) :-
   log_nameOf(Context, Formula),
   formula_binary(Formula, Subject, Predicate, Object).

package/examples/control-system.pl

@@ -3,11 +3,13 @@
 % The example combines measurements, observations, targets, logarithmic
 % feedforward compensation, square-root normalization, and nonlinear feedback.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(controlSignal, 2).
 materialize(status, 2).
 materialize(normalizedMeasurement, 2).
 materialize(log10, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 measurement(input1, [6, 11]).
 measurement(disturbance2, [45, 39]).
 measurement(input2, true).
@@ -21,6 +23,7 @@ observation(state3, 22).
 
 target(output2, 29).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 measurement_normalized(I, M) :-
   measurement(I, [M1, M2]),
   lt(M1, M2),

package/examples/cryptarithmetic-send-more-money.pl

@@ -5,10 +5,13 @@
 % a six-column addition.  Each column constraint is applied as soon as possible
 % so the finite digit search prunes early without cut.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(status, 2).
 materialize(assignment, 2).
 materialize(equation, 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.
 send_more_money(solution(S, E, N, D, M, O, R, Y), Send, More, Money) :-
   alphametic_sum(
     [s, e, n, d, m, o, r, y],

package/examples/cyclic-path.pl

@@ -2,13 +2,15 @@
 % variant loop guard prevents recursive proof search from revisiting the same
 % active subgoal forever.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(path, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 arc(a, b).
 arc(b, c).
 arc(c, d).
 arc(d, a).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 path(X, Y) :- arc(X, Y).
 path(X, Z) :- arc(X, Y), path(Y, Z).
-

package/examples/d3-group.pl

@@ -1,10 +1,13 @@
 % Eyelet-inspired D3 group example using findall/3 and sort/2.
 % It enumerates subgroups of the dihedral group of order 6.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(subgroups, 2).
 materialize(subgroupCount, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Six symmetries of an equilateral triangle: identity, rotations, reflections.
 symmetry(identity).
 symmetry(rotation_120).
 symmetry(rotation_240).
@@ -12,6 +15,7 @@ symmetry(reflection_a).
 symmetry(reflection_b).
 symmetry(reflection_c).
 
+% Cayley table for D3 composition.
 compose(identity, identity, identity).
 compose(identity, rotation_120, rotation_120).
 compose(identity, rotation_240, rotation_240).
@@ -48,6 +52,7 @@ compose(reflection_c, rotation_240, reflection_a).
 compose(reflection_c, reflection_a, rotation_240).
 compose(reflection_c, reflection_b, rotation_120).
 compose(reflection_c, reflection_c, identity).
+% Each candidate subgroup must also contain inverses.
 inverse(identity, identity).
 inverse(rotation_120, rotation_240).
 inverse(rotation_240, rotation_120).
@@ -55,7 +60,9 @@ inverse(reflection_a, reflection_a).
 inverse(reflection_b, reflection_b).
 inverse(reflection_c, reflection_c).
 
+% Candidate subsets are generated as subsequences of the sorted symmetry list.
 subsequence([], []).
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 subsequence([Head | Tail], [Head | Rest]) :-
   subsequence(Tail, Rest).
 subsequence([_Head | Tail], Rest) :-
@@ -65,6 +72,7 @@ all_symmetries(Symmetries) :-
   findall(X, symmetry(X), Raw),
   sort(Raw, Symmetries).
 
+% A valid subgroup is closed under both composition and inverse.
 closed_under_composition(Group) :-
   not((member(X, Group), member(Y, Group), compose(X, Y, Z), not(member(Z, Group)))).
 

package/examples/dairy-energy-balance.pl

@@ -2,17 +2,20 @@
 % Cows are classified from maintenance, milk requirement, and ration supply.
 
 % cow(Cow, BodyWeightKg, MilkKgPerDay, RationEnergyMcalPerKgDM, IntakeKgDM).
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(energyBalance_Mcal, 2).
 materialize(rationSupportedMilk_kg, 2).
 materialize(status, 2).
 materialize(reason, 2).
 materialize(strongestDeficit, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 cow(early_lactation, 650, 38, 6.4, 22).
 cow(mid_lactation, 610, 24, 6.5, 26).
 cow(late_lactation, 580, 16, 6.7, 25).
 cow(grazing, 540, 18, 5.8, 21).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 maintenance(C, M) :-
   cow(C, Weight, _, _, _),
   mul(Weight, 0.08, M).

package/examples/data-negotiation.pl

@@ -1,8 +1,11 @@
 % Data negotiation with policies, adapted from Eyelet input/data-negotiation.pl.
 % The accepted negotiation matches Eyelet output-swipl/data-negotiation.pl.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(negotiate, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Each agent has local data, desired remote data, and a simple policy.
 hasData(agent1, [data1, data2, data3]).
 hasData(agent2, [data4, data5, data6]).
 
@@ -10,11 +13,13 @@ want_negotiate(agent1, [agent2, data4]).
 want_negotiate(agent1, [agent2, data5]).
 want_negotiate(agent1, [agent2, data7]).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 policy(agent1, [request, Data]) :-
   member(Data, [data4, data6]).
 policy(agent2, [accept, Data]) :-
   neq(Data, data5).
 
+% A request is possible only if A lacks the data and A's policy allows asking for it.
 request_data(AgentA, AgentB, Data) :-
   hasData(AgentA, DataListA),
   hasData(AgentB, DataListB),
@@ -22,6 +27,7 @@ request_data(AgentA, AgentB, Data) :-
   not_member(Data, DataListA),
   policy(AgentA, [request, Data]).
 
+% B accepts only requests for data it has and its own policy permits sharing.
 accept_request(AgentB, _AgentA, Data) :-
   hasData(AgentB, DataListB),
   member(Data, DataListB),

package/examples/deep-taxonomy-10.pl

@@ -8,6 +8,7 @@
 % long adjacent-only proof after a shorter checkpoint proof has succeeded.
 % =============================================================================================================================
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(is, 2).
 materialize(answer, 2).
 materialize(reason, 2).
@@ -15,12 +16,14 @@ materialize(result, 2).
 materialize(checkPassed, 2).
 materialize(arc, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % fact
 
 a(ind, n0).
 
 % terminal rule
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 is(test, true) :- once(a(ind, a2)).
 a(X, a2) :- a(X, n10).
 

package/examples/deep-taxonomy-100.pl

@@ -8,6 +8,7 @@
 % long adjacent-only proof after a shorter checkpoint proof has succeeded.
 % =============================================================================================================================
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(is, 2).
 materialize(answer, 2).
 materialize(reason, 2).
@@ -15,12 +16,14 @@ materialize(result, 2).
 materialize(checkPassed, 2).
 materialize(arc, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % fact
 
 a(ind, n0).
 
 % terminal rule
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 is(test, true) :- once(a(ind, a2)).
 a(X, a2) :- a(X, n100).
 

package/examples/deep-taxonomy-1000.pl

@@ -8,6 +8,7 @@
 % long adjacent-only proof after a shorter checkpoint proof has succeeded.
 % =============================================================================================================================
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(is, 2).
 materialize(answer, 2).
 materialize(reason, 2).
@@ -15,12 +16,14 @@ materialize(result, 2).
 materialize(checkPassed, 2).
 materialize(arc, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % fact
 
 a(ind, n0).
 
 % terminal rule
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 is(test, true) :- once(a(ind, a2)).
 a(X, a2) :- a(X, n1000).
 

package/examples/deep-taxonomy-10000.pl

@@ -8,6 +8,7 @@
 % long adjacent-only proof after a shorter checkpoint proof has succeeded.
 % =============================================================================================================================
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(is, 2).
 materialize(answer, 2).
 materialize(reason, 2).
@@ -15,12 +16,14 @@ materialize(result, 2).
 materialize(checkPassed, 2).
 materialize(arc, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % fact
 
 a(ind, n0).
 
 % terminal rule
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 is(test, true) :- once(a(ind, a2)).
 a(X, a2) :- a(X, n10000).
 

package/examples/deep-taxonomy-100000.pl

@@ -8,6 +8,7 @@
 % long adjacent-only proof after a shorter checkpoint proof has succeeded.
 % =============================================================================================================================
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(is, 2).
 materialize(answer, 2).
 materialize(reason, 2).
@@ -15,12 +16,14 @@ materialize(result, 2).
 materialize(checkPassed, 2).
 materialize(arc, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % fact
 
 a(ind, n0).
 
 % terminal rule
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 is(test, true) :- once(a(ind, a2)).
 a(X, a2) :- a(X, n100000).
 

package/examples/delfour.pl

@@ -8,6 +8,7 @@
 % Rules project only the fields they need, avoiding global permission/prohibition
 % facts that could contradict another policy formula in the same program.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(caseName, 2).
 materialize(needsLowSugar, 2).
 materialize(derivedFromNeed, 2).
@@ -39,6 +40,8 @@ materialize(dutyTimingConsistent, 2).
 materialize(marketingProhibited, 2).
 materialize(filesWrittenExpected, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Formula-valued facts keep each input graph scoped and easy to project.
 case_graph(delfourCaseGraph, (
   caseName(case, "delfour"),
   requestPurpose(case, "shopping_assist"),
@@ -53,6 +56,7 @@ case_graph(delfourCaseGraph, (
   scannedProduct(scan, prod_BIS_001)
 )).
 
+% Catalog rows are product(IdTerm, DisplayId, Name, SugarTenths, SugarG).
 product_catalog(delfourCatalog, [
   product(prod_BIS_001, "prod_BIS_001", "Classic Tea Biscuits", 120, 12.0),
   product(prod_BIS_101, "prod_BIS_101", "Low-Sugar Tea Biscuits", 30, 3.0),
@@ -97,6 +101,7 @@ signature_graph(delfourSignatureGraph, (
 
 reason_text(reasonText, "Household requires low-sugar guidance (diabetes in POD). A neutral Insight is scoped to device 'self-scanner', event 'pick_up_scanner', retailer 'Delfour', and expires soon; the policy confines use to shopping assistance.").
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 case_statement(S, P, O) :- case_graph(delfourCaseGraph, Formula), formula_binary(Formula, S, P, O).
 insight_statement(S, P, O) :- insight_graph(delfourInsightGraph, Formula), formula_binary(Formula, S, P, O).
 policy_statement(S, P, O) :- policy_graph(delfourPolicyGraph, Formula), formula_binary(Formula, S, P, O).
@@ -149,6 +154,7 @@ payload_hash_sha256(signature, Hash) :- signature_statement(signature, payloadHa
 signature_hmac(signature, Hmac) :- signature_statement(signature, hmac, Hmac).
 hmac_verification_mode(signature, Mode) :- signature_statement(signature, hmacVerificationMode, Mode).
 
+% The household profile creates the low-sugar need used by the insight.
 needs_low_sugar(case) :-
   condition(householdProfile, "Diabetes").
 
@@ -200,6 +206,7 @@ better_lower_sugar(ScannedSugar, CandidateSugar) :-
   gt(ScannedSugar, OtherSugar),
   lt(OtherSugar, CandidateSugar).
 
+% Pick the lowest-sugar alternative according to the insight suggestion policy.
 suggested_alternative(case, Candidate) :-
   scanned_product(scan, Scanned),
   sugar_tenths(Scanned, ScannedSugar),

package/examples/dense-hamiltonian-cycle.pl

@@ -5,11 +5,13 @@
 % scores the closed cycles, and keeps the cheapest candidate with
 % aggregate_min/5.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(best, 2).
 materialize(candidateCount, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 cities([a, b, c, d, e, f, g, h]).
 
 edge(a, b, 3).
@@ -41,6 +43,7 @@ edge(f, g, 8).
 edge(f, h, 45).
 edge(g, h, 9).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 weight(A, B, W) :- edge(A, B, W).
 weight(A, B, W) :- edge(B, A, W).
 

package/examples/deontic-logic.pl

@@ -1,9 +1,12 @@
 % Deontic logic: obligations, prohibitions, compensations, and violations.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(violation, 2).
 materialize(compensation, 2).
 materialize(status, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Facts state what the actor was obliged/prohibited to do and what happened.
 actor(alice).
 action(share_record).
 action(delete_unneeded_copy).
@@ -17,6 +20,8 @@ performed(alice, notify_dpo).
 not_performed(alice, obtain_consent).
 not_performed(alice, delete_unneeded_copy).
 
+% Missing an obligation and performing a prohibited action are both violations.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 violation(Actor, missed_obligation(Action)) :-
   obliged(Actor, Action),
   not_performed(Actor, Action).
@@ -25,6 +30,7 @@ violation(Actor, prohibited_action(Action)) :-
   prohibited(Actor, Action),
   performed(Actor, Action).
 
+% Some prohibited actions can be repaired by a configured compensation action.
 compensated_violation(Actor, Action, Compensation) :-
   prohibited(Actor, Action),
   performed(Actor, Action),

package/examples/derived-backward-rule.pl

@@ -10,13 +10,16 @@
 % log_impliedBy/2, then mirrored as an ordinary eyelang rule so the generated
 % childOf relation can feed the ordinary hasParent rule.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(log_impliedBy, 2).
 materialize(childOf, 2).
 materialize(hasParent, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 invOf(parentOf, childOf).
 parentOf(alice, bob).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 log_impliedBy(childOf(var(x), var(y)), parentOf(var(y), var(x))) :-
   invOf(parentOf, childOf).
 

package/examples/derived-rule.pl

@@ -9,13 +9,16 @@
 % var(y) is not an eyelang variable; it is a ground term that names
 % a variable placeholder inside the quoted formula.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(type, 2).
 materialize(log_implies, 2).
 materialize(is, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 type(minka, cat).
 type(charly, dog).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 log_implies(type(var(y), dog), is(test, true)) :-
   type(_X, cat).
 

package/examples/diamond-property.pl

@@ -4,10 +4,12 @@
 % source can be joined again.  This compact eyelang version keeps the same
 % diamond idea and also checks that it is preserved by reflexive closure.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(holdsFor, 2).
 materialize(commonSuccessor, 2).
 materialize(preservedUnderReflexiveClosure, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 node(a).
 node(b).
 node(c).
@@ -18,6 +20,7 @@ r(a, c).
 r(b, d).
 r(c, d).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 re(X, X) :- node(X).
 re(X, Y) :- r(X, Y).
 

package/examples/dijkstra-findall-sort.pl

@@ -1,10 +1,13 @@
 % Eyelet-inspired Dijkstra example using findall/3 and sort/2.
 % Adapted to eyelang's explicit built-ins and relation report style.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(shortestPath, 2).
 materialize(cost, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Weighted undirected graph; the symmetric edge rule below adds reverse arcs.
 edge(a, b, 4).
 edge(a, c, 2).
 edge(b, c, 1).
@@ -14,14 +17,17 @@ edge(c, e, 10).
 edge(d, e, 2).
 edge(d, f, 6).
 edge(e, f, 3).
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 edge(A, B, Cost) :- edge(B, A, Cost).
 
+% The frontier is represented as [Cost, Node | ReversePath] entries.
 dijkstra(Start, Goal, Path, Cost) :-
   dijkstra_queue([[0, Start]], Goal, [], RevPath, Cost),
   reverse(RevPath, Path).
 
 dijkstra_queue([[Cost, Goal | Path] | _Queue], Goal, _Visited, [Goal | Path], Cost).
 dijkstra_queue([[Cost, Node | Path] | Queue], Goal, Visited, ResultPath, ResultCost) :-
+  % Expand all unvisited neighbors, then sort so the cheapest frontier wins.
   findall([NewCost, Neighbor, Node | Path],
     (edge(Node, Neighbor, Weight), not(member(Neighbor, Visited)), add(Cost, Weight, NewCost)),
     Neighbors),

package/examples/dijkstra-risk-path.pl

@@ -1,5 +1,6 @@
 % Memoize route costs: selected paths, route relations, and trust checks reuse
 % the same path-list reductions.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(route, 2).
 materialize(rawCost, 2).
 materialize(riskSum, 2).
@@ -10,6 +11,7 @@ materialize(trustGate, 2).
 materialize(notes, 2).
 materialize(selects, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 memoize(route_cost, 4).
 
 % Risk-adjusted route selection adapted from Eyeling dijkstra-risk-path.n3.
@@ -28,6 +30,7 @@ route_network(riskNetwork, (
   segment(depotA, segment(labD, 14.0, 0.05))
 )).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 route_segment(From, To, Raw, Risk) :-
   route_network(riskNetwork, Formula),
   formula_binary(Formula, From, segment, segment(To, Raw, Risk)).

package/examples/dijkstra.pl

@@ -5,9 +5,11 @@
 % The input weighted graph is quoted as ... data and projected locally,
 % so the route network is not asserted as ambient edge facts.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(edge, 2).
 materialize(path, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 weighted_graph(dijkstraGraph, (
   edge(a, arc(b, 4)),
   edge(a, arc(c, 2)),
@@ -20,6 +22,7 @@ weighted_graph(dijkstraGraph, (
   edge(e, arc(f, 3))
 )).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 base_link(A, B, Cost) :-
   weighted_graph(dijkstraGraph, Formula),
   formula_binary(Formula, A, edge, arc(B, Cost)).

package/examples/dining-philosophers.pl

@@ -1,6 +1,7 @@
 % Chandy-Misra dining philosophers trace adapted from Eyeling dining-philosophers.n3.
 % Requests and sends are derived; KeepFork facts copy forks that are not sent.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(dp_type, 2).
 materialize(dp_in, 2).
 materialize(dp_from, 2).
@@ -11,6 +12,7 @@ materialize(dp_mealNo, 2).
 materialize(dp_inSlot, 2).
 materialize(dp_usesFork, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 left_fork(dp_P1, dp_F51). right_fork(dp_P1, dp_F12).
 left_fork(dp_P2, dp_F12). right_fork(dp_P2, dp_F23).
 left_fork(dp_P3, dp_F23). right_fork(dp_P3, dp_F34).
@@ -98,6 +100,7 @@ meal_handle(dp_P3, 1, dp_mP3_1). meal_handle(dp_P3, 2, dp_mP3_2). meal_handle(dp
 meal_handle(dp_P4, 1, dp_mP4_1). meal_handle(dp_P4, 2, dp_mP4_2). meal_handle(dp_P4, 3, dp_mP4_3).
 meal_handle(dp_P5, 1, dp_mP5_1). meal_handle(dp_P5, 2, dp_mP5_2). meal_handle(dp_P5, 3, dp_mP5_3).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 request(C, P, Q, F) :-
   hungry(C, P), left_fork(P, F), start_state(C, F, Q, _Cleanliness), neq(Q, P).
 request(C, P, Q, F) :-

package/examples/dog.pl

@@ -1,5 +1,8 @@
+% The output reports only the compliance obligation derived below.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(mustHave, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % Dog-license example adapted from Eyeling dog.n3.
 % A subject with more than four dogs must have a dog license.
 
@@ -11,6 +14,8 @@ hasDog(alice, dog5).
 hasDog(bob, dog6).
 hasDog(bob, dog7).
 
+% countall/2 counts all matching dogs for the same subject.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 dogCount(Subject, Count) :-
   hasDog(Subject, _Any),
   countall(hasDog(Subject, _Dog), Count).

package/examples/drone-corridor-planner.pl

@@ -1,6 +1,8 @@
 % Memoize bounded paths because surviving-plan metrics reuse route prefixes.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(gps_plan, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 memoize(path, 9).
 
 % Bounded drone corridor planner adapted from Eyeling drone-corridor-planner.n3.
@@ -24,6 +26,7 @@ step(state(brugge, mid, P), state(oostende, low, P), public_coastline_brugge_oos
 step(state(brugge, full, P), state(oostende, mid, P), public_coastline_brugge_oostende, 1200.0, 0.006, 0.975, 0.96).
 step(state(kortrijk, full, yes), state(oostende, mid, yes), direct_corridor_kortrijk_oostende, 1100.0, 0.009, 0.955, 0.92).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 path(From, To, [Act], Duration, Cost, Belief, Comfort, FuelIn, FuelOut) :-
   step(From, To, Act, Duration, Cost, Belief, Comfort),
   rest(FuelIn, FuelOut).

package/examples/easter-computus.pl

@@ -1,10 +1,13 @@
 % Adapted from Eyeling's easter.n3.
 % Gregorian computus for a sample decade, with independent range/window checks.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(easterDate, 2).
 materialize(computusRemainders, 2).
 materialize(legalGregorianWindow, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Sample years for which the computed Easter date is materialized.
 case(y2026, 2026).
 case(y2027, 2027).
 case(y2028, 2028).
@@ -16,6 +19,8 @@ case(y2033, 2033).
 case(y2034, 2034).
 case(y2035, 2035).
 
+% These checks document the legal ranges of intermediate computus values.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 valid_golden(N) :- between(0, 18, N).
 valid_epact(N) :- between(0, 29, N).
 valid_weekday(N) :- between(0, 6, N).
@@ -24,6 +29,7 @@ legal_easter_date(4, D) :- between(1, 25, D).
 month_name(3, march).
 month_name(4, april).
 
+% Butcher/Meeus-style integer arithmetic, kept explicit for proof readability.
 computus(Case, Year, Month, Day, J, K, Q, R, V, Z) :-
   case(Case, Year),
   mod(Year, 19, J),

package/examples/electrical-rc-filter.pl

@@ -2,14 +2,17 @@
 %
 % The cutoff frequency is 1 / (2*pi*R*C).
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(type, 2).
 materialize(timeConstant_s, 2).
 materialize(cutoffFrequency_Hz, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 component(filter1, resistor_ohm, 10000.0).
 component(filter1, capacitor_f, 0.000001).
 constant(pi, 3.141592653589793).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 time_constant(Filter, Tau) :-
   component(Filter, resistor_ohm, R),
   component(Filter, capacitor_f, C),