eyelang 1.5.3 → 1.5.4

package/examples/access-control-policy.pl

@@ -4,10 +4,12 @@
 % finite logical conditions.  The universal allOf/noneOf checks use negation
 % as failure over bound policy facts.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(policy, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 policy_request(test1, policy_x).
 has(test1, claim_a).
 has(test1, claim_b).
@@ -19,6 +21,7 @@ allOf(policy_x, claim_b).
 anyOf(policy_x, claim_c).
 noneOf(policy_x, claim_d).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 passes_all_of(Request, Policy) :-
   policy_request(Request, Policy),
   policy(Policy),

package/examples/ackermann.pl

@@ -2,8 +2,11 @@
 % The two-argument entry point follows the Eyeling encoding:
 %   ackermann(X, Y) = hyper(X, Y + 3, 2) - 3.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(ackermann, 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.
 ackermann(X, Y, A) :-
   add(Y, 3, B),
   hyper(X, B, 2, C),

package/examples/age.pl

@@ -3,16 +3,19 @@
 % Is the age of a person above some duration?
 
 % Person data.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(birthDay, 2).
 materialize(duration, 2).
 materialize(ageAbove, 2).
 materialize(is, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 birthDay(patH, "1944-08-21").
 duration(check, "P80Y").
 
 % A person is above a duration if the local date minus the birthday is greater
 % than that duration.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 ageAbove(S, A) :-
   birthDay(S, B),
   duration(check, A),

package/examples/aliases-and-namespaces.pl

@@ -1,15 +1,22 @@
 % Built-ins use one native spelling each.
 % Vocabulary predicate names remain ordinary user predicates.
 
+% The materialized relations below show that built-ins can coexist with
+% ordinary vocabulary predicates that happen to look namespace-like.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(value, 2).
 materialize(ok, 2).
 materialize(tail, 2).
 materialize(label, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Native operations are called through their canonical predicate names.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 value(nativeMath, X) :- add(0.125, 0.875, X).
 ok(nativeCompare, true) :- lt(2, 3).
 ok(nativeString, true) :- matches("scoped retail insight", "retail|medical").
 tail(nativeList, Tail) :- rest([a, b, c], Tail).
 
+% These names are just user data; eyelang does not give them special meaning.
 example_label(vocabularyExample, "vocabulary names are ordinary predicate names").
 label(vocabularyExample, Text) :- example_label(vocabularyExample, Text).

package/examples/alignment-demo.pl

@@ -4,6 +4,7 @@
 % broader/narrower alignments, their transitive closure, the reflexive
 % narrower-or-equal relation, and the concepts that roll up to ref_car.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(broader, 2).
 materialize(narrower, 2).
 materialize(broaderTransitive, 2).
@@ -11,6 +12,7 @@ materialize(narrowerTransitive, 2).
 materialize(narrowerOrEqualOf, 2).
 materialize(rollsUpTo, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 concept(ref_car).
 concept(tel_car).
 concept(tel_heavy_vehicle).
@@ -22,6 +24,7 @@ assertedBroader(tel_heavy_vehicle, ref_car).
 assertedBroader(anpr_vehicle_with_plate, ref_car).
 assertedNarrower(anpr_vehicle_with_plate, anpr_passenger_car).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 broader(X, Y) :- assertedBroader(X, Y).
 broader(X, Y) :- assertedNarrower(Y, X).
 

package/examples/allen-interval-calculus.pl

@@ -4,11 +4,13 @@
 % The input interval table is a list of records, showing how tabular data can
 % stay scoped as one term instead of many unrelated global start/end facts.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(start, 2).
 materialize(end, 2).
 materialize(duration, 2).
 materialize(statement, 3).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 interval_table([
   interval(a, 10, 12),
   interval(b, 13, 15),
@@ -23,6 +25,7 @@ interval_table([
   interval(k, 13, 14)
 ]).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 interval(I) :- interval_table(Table), member(interval(I, _Start, _End), Table).
 start(I, Start) :- interval_table(Table), member(interval(I, Start, _End), Table).
 end(I, End) :- interval_table(Table), member(interval(I, _Start, End), Table).

package/examples/ancestor.pl

@@ -1,14 +1,21 @@
 % Basic recursive relation example.
+% Both input facts and derived recursive answers are printed.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(parent, 2).
 materialize(ancestor, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% Direct parent facts form a simple chain.
 parent(pat, jan).
 parent(jan, lies).
 parent(lies, emma).
 
+% Base case: every parent is also an ancestor.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 ancestor(X, Y) :-
   parent(X, Y).
 
+% Recursive case: walk one parent edge and continue through the chain.
 ancestor(X, Z) :-
   parent(X, Y),
   ancestor(Y, Z).

package/examples/animal.pl

@@ -3,13 +3,16 @@
 % The Eyelet source uses Unicode predicate names; this eyelang version keeps the
 % same tiny inheritance idea with plain vocabulary names.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(type, 2).
 materialize(subclassOf, 2).
 materialize(succeeds, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 human(joe).
 animal(human).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 animal(X) :- human(X).
 
 type(joe, human) :- human(joe).

package/examples/annotation.pl

@@ -3,17 +3,20 @@
 % The program keeps the annotation as data and derives visible relations from it.
 % Formula members become default output only when explicit rules project them.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(name, 2).
 materialize(log_nameOf, 2).
 materialize(statedBy, 2).
 materialize(recorded, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 annotation(t, (
   name(a, "Alice"),
   statedBy(t, bob),
   recorded(t, "2021-07-07")
 )).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 name(S, O) :-
   annotation(_T, Formula),
   formula_binary(Formula, S, name, O).

package/examples/auroracare.pl

@@ -3,6 +3,7 @@
 % translation materializes the policy decisions, reasons, traces, and ARC-style
 % check values as ordinary relation output.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(label, 2).
 materialize(description, 2).
 materialize(careTeamLinked, 2).
@@ -24,9 +25,11 @@ materialize(checkC8, 2).
 materialize(checkC9, 2).
 materialize(checkC10Text, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 caseName(case, "auroracare").
 question(case, "For each AuroraCare scenario, should the PDP permit or deny the requested use of health data, and why?").
 
+% Policies: primary care, quality improvement, research, and an explicit denial.
 policyUid(policyPrimary, "urn:policy:primary-care-001").
 purposeAllowed(policyPrimary, primaryCareManagement).
 purposeAllowed(policyPrimary, patientRemoteMonitoring).
@@ -64,6 +67,7 @@ primaryPurpose(auroracare, primaryCareManagement).
 primaryPurpose(auroracare, patientRemoteMonitoring).
 prohibitedPurpose(auroracare, insuranceManagement).
 
+% Scenarios A-G mirror the upstream Markdown report cases.
 scenario(scenarioA).
 outputKey(scenarioA, out010A).
 scenario_label(scenarioA, "A – Primary care visit").
@@ -145,6 +149,7 @@ environment(scenarioG, "secure_env").
 category(scenarioG, patientSummary).
 category(scenarioG, labResults).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 label(S, Label) :- scenario_label(S, Label).
 description(S, Description) :- scenario_description(S, Description).
 
@@ -195,9 +200,11 @@ careTeamLinked(S, true) :- care_team_linked(S).
 subjectOptIn(S, true) :- subject_opt_in(S).
 subjectOptOut(S, true) :- subject_opt_out(S).
 
+% Permit when a scenario satisfies one of the allowed policy branches.
 decision(S, "PERMIT") :- primary_policy_match(S).
 decision(S, "PERMIT") :- qi_policy_match(S).
 decision(S, "PERMIT") :- research_policy_match(S).
+% Deny branches preserve the reason that will be materialized for the report.
 decision(S, "DENY") :- insurance_prohibition_match(S).
 decision(S, "DENY") :- ai_training_opt_out_match(S).
 decision(scenarioC, "DENY") :- purpose(scenarioC, ensureQualitySafetyHealthcare).
@@ -223,6 +230,7 @@ trace(S, "urn:policy:deny-insurance:deny:odrl:prohibition_matched") :- insurance
 trace(S, "deny:subject_opted_out_ai_training") :- ai_training_opt_out_match(S).
 trace(scenarioC, "urn:policy:qi-2025-aurora:deny:odrl:no_permission_matched") :- purpose(scenarioC, ensureQualitySafetyHealthcare).
 
+% C1-C10 below are the ARC-style checklist lines from the upstream output.
 checkC1(scenarioA, "SKIPPED - not a prohibited purpose") :- decision(scenarioA, "PERMIT").
 checkC2(scenarioA, "OK - clinician") :- decision(scenarioA, "PERMIT").
 checkC3(scenarioA, "OK - care-team linked") :- decision(scenarioA, "PERMIT").

package/examples/backward.pl

@@ -1,9 +1,12 @@
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(isIndeedMoreInterestingThan, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % Backward rule example adapted from Eyeling backward.n3.
 % Eyeling writes the interestingness rule backward; eyelang records the same
 % relation as an ordinary rule whose body is the numeric comparison.
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 moreInterestingThan(X, Y) :- gt(X, Y).
 
 isIndeedMoreInterestingThan(5, 3) :- moreInterestingThan(5, 3).

package/examples/basic-monadic.pl

@@ -8,8 +8,10 @@
 % EYE reasoning/basic-monadic/10tt_answer.n3 in cardinality and content
 % after translating N3 statements to eyelang relation terms.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(cycle, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 edge(i30, i12, i33).
 edge(i61, i29, i42).
 edge(i57, i46, i87).
@@ -10011,6 +10013,6 @@ edge(i18, i75, i36).
 edge(i48, i89, i48).
 edge(i26, i42, i54).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 cycle(R, Cycle) :-
   fixed_length_cycle(edge, 10, R, Cycle).
-

package/examples/bayes-diagnosis.pl

@@ -4,6 +4,7 @@
 % points, so this example is comparable with examples/output/bayes-diagnosis.n3
 % in the Eyeling repository.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(scores, 2).
 materialize(evidenceTotal, 2).
 materialize(result, 2).
@@ -11,6 +12,7 @@ materialize(disease, 2).
 materialize(unnormalized, 2).
 materialize(posterior, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 disease(covid19).
 disease(influenza).
 disease(allergicRhinitis).
@@ -53,6 +55,7 @@ evidence([
   ev(shortBreath, true)
 ]).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 factor(Disease, Symptom, true, P) :- p_given(Disease, Symptom, P).
 factor(Disease, Symptom, false, Q) :-
   p_given(Disease, Symptom, P),

package/examples/bayes-therapy.pl

@@ -1,5 +1,6 @@
 % Memoize shared inference layers: the score vector, disease likelihood tails,
 % and expected therapy success are reused by several report relations.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(diseases, 2).
 materialize(therapies, 2).
 materialize(evidence, 2).
@@ -12,6 +13,7 @@ materialize(expectedAdverse, 2).
 materialize(utility, 2).
 materialize(recommendedTherapy, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 memoize(scores_for, 2).
 memoize(likelihood, 3).
 memoize(expected_success, 2).
@@ -81,6 +83,7 @@ adverse(supportiveCare, 0.01).
 benefit_weight(10).
 harm_weight(3).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 factor(Disease, ev(Symptom, true), P) :- p_given(Disease, Symptom, P).
 factor(Disease, ev(Symptom, false), Q) :-
   p_given(Disease, Symptom, P),

package/examples/beam-deflection.pl

@@ -2,18 +2,21 @@
 %
 % The tip deflection for a point load at the free end is F*L^3/(3*E*I).
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(type, 2).
 materialize(tipDeflection_m, 2).
 materialize(tipDeflection_mm, 2).
 materialize(limit_mm, 2).
 materialize(status, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 beam(beam1, force_N, 1200.0).
 beam(beam1, length_m, 2.5).
 beam(beam1, elasticModulus_Pa, 200000000000.0).
 beam(beam1, secondMoment_m4, 0.000008).
 limit(beam1, maxDeflection_mm, 5.0).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 tip_deflection_m(Beam, Deflection) :-
   beam(Beam, force_N, Force),
   beam(Beam, length_m, Length),

package/examples/blocks-world-planning.pl

@@ -4,11 +4,13 @@
 % are sorted lists of on(Block, Support) facts so equality and visited-state
 % checks are purely structural.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(status, 2).
 materialize(plan, 2).
 materialize(finalState, 2).
 materialize(blockCount, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 initial([on(a, table), on(b, a), on(c, b), on(d, c), on(e, d)]).
 goal([on(a, table), on(b, a), on(c, table), on(d, c), on(e, d)]).
 
@@ -19,6 +21,7 @@ block(d).
 block(e).
 
 support(table, _State).
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 support(Block, State) :-
   block(Block),
   member(on(Block, _Below), State).

package/examples/bmi.pl

@@ -7,6 +7,7 @@
 % For reproducibility and documentation only; not medical advice.
 
 % Editable metric input.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(unitSystem, 2).
 materialize(weight, 2).
 materialize(height, 2).
@@ -39,6 +40,7 @@ materialize(result, 2).
 materialize(healthyWeightRangeKg, 2).
 materialize(checkPassed, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 unitSystem(input, metric).
 weight(input, 72.0).
 height(input, 178.0).
@@ -49,6 +51,7 @@ height(input, 178.0).
 % height(input, 70.08).
 
 % Normalization and BMI calculation.
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 weightKg(case, W) :-
   unitSystem(input, metric),
   weight(input, W).

package/examples/braking-safety-worlds.pl

@@ -3,11 +3,13 @@
 % 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).
@@ -18,6 +20,7 @@ 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),

package/examples/buck-converter-design.pl

@@ -3,6 +3,7 @@
 % 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.
 materialize(dutyCycle, 2).
 materialize(inductorRipple_A, 2).
 materialize(rippleRatio, 2).
@@ -10,6 +11,7 @@ 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).
@@ -19,6 +21,7 @@ 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),

package/examples/cache-performance.pl

@@ -4,15 +4,18 @@
 % 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).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 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).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 total_requests(Cache, Total) :-
   cache_sample(Cache, Hits, Misses, _HitLatency, _MissLatency),
   add(Hits, Misses, Total).

package/examples/canary-release.pl

@@ -3,16 +3,19 @@
 % 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).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 canary(canary42, 5000.0, 75.0, 180.0).
 threshold(canary42, maximum_error_rate, 0.01).
 threshold(canary42, maximum_p95_latency_ms, 200.0).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 error_rate(Release, Rate) :-
   canary(Release, Requests, Errors, _P95Latency),
   div(Errors, Requests, Rate).

package/examples/cat-koko.pl

@@ -4,14 +4,17 @@
 % 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).
 

package/examples/clinical-trial-screening.pl

@@ -4,10 +4,12 @@
 % 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.
 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).
@@ -35,6 +37,7 @@ 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),

package/examples/collatz-1000.pl

@@ -1,11 +1,14 @@
 % Memoize trajectories because different start values quickly merge into
 % shared Collatz tails.
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(collatzTrajectory, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 % Collatz trajectory benchmark adapted from Eyeling collatz-1000.n3.
 % The reusable builtin keeps this large output example focused on data volume
 % rather than recursive integer arithmetic overhead.
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 collatzTrajectory(N, Trajectory) :-
   between(1, 1000, N),
   collatz_trajectory(N, Trajectory).

package/examples/combinatorics-findall-sort.pl

@@ -1,14 +1,19 @@
 % Eyelet-inspired combinations example using findall/3 and sort/2.
 % The source-level select/3 relation remains an ordinary eyelang rule.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(combinations, 2).
 materialize(count, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
+% select/3 nondeterministically removes one item from a list.
 select(Item, [Item | Rest], Rest).
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 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),
@@ -17,6 +22,7 @@ combination(I, Items, Combination) :-
   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).

package/examples/competitive-enzyme-kinetics.pl

@@ -4,6 +4,7 @@
 %   Km_effective = Km * (1 + Inhibitor / Ki)
 %   rate = Vmax * Substrate / (Km_effective + Substrate)
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(effectiveKm_uM, 2).
 materialize(uninhibitedRate_uM_s, 2).
 materialize(inhibitedRate_uM_s, 2).
@@ -11,6 +12,7 @@ materialize(inhibitionFraction, 2).
 materialize(status, 2).
 materialize(reason, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 assay(assay1, vmax_uM_s, 120.0).
 assay(assay1, substrate_uM, 50.0).
 assay(assay1, km_uM, 30.0).
@@ -18,6 +20,7 @@ assay(assay1, inhibitor_uM, 10.0).
 assay(assay1, ki_uM, 5.0).
 threshold(assay1, significant_inhibition_fraction, 0.25).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 competitive_multiplier(Assay, Multiplier) :-
   assay(Assay, inhibitor_uM, Inhibitor),
   assay(Assay, ki_uM, Ki),

package/examples/complex-matrix-stability.pl

@@ -3,14 +3,17 @@
 % trace < 0 and determinant > 0.  A negative discriminant indicates a
 % complex-conjugate eigenvalue pair.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(trace, 2).
 materialize(determinant, 2).
 materialize(discriminant, 2).
 materialize(eigenShape, 2).
 materialize(status, 2).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 matrix(controller_loop, -0.7, 1.2, -0.4, -0.5).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 trace(Matrix, Trace) :-
   matrix(Matrix, A, _B, _C, D),
   add(A, D, Trace).

package/examples/complex.pl

@@ -3,11 +3,14 @@
 % Complex values are represented as two-item lists [Real, Imaginary], matching
 % the pair-shaped pair lists used by the Eyeling source.
 
+% 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.
 pi(3.141592653589793).
 e(2.718281828459045).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 complex_exponentiation([A, B], [C, D], [E, F]) :-
   complex_polar([A, B], [R, T]),
   pow(R, C, Z1),

package/examples/composition-of-injective-functions-is-injective.pl

@@ -4,14 +4,17 @@
 % The output mirrors the Eyeling golden result shape:
 % sameInputByCompositeInjectivity(h, a, b) and the symmetric counterpart.
 
+% Output declarations: materialize/2 selects the relations written to this example's golden output.
 materialize(sameInputByCompositeInjectivity, 3).
 
+% Program structure: facts set up the scenario, and rules derive the materialized conclusions.
 inX(a).
 inX(b).
 inY(c).
 inY(d).
 inZ(e).
 
+% Derivation rules: each rule below contributes one logical step toward the displayed results.
 sameTerm(X, X) :- inX(X).
 sameTerm(X, X) :- inY(X).
 sameTerm(X, X) :- inZ(X).