eyelang 1.5.2 → 1.5.4

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).

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,15 +8,22 @@
 % 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).
 materialize(outcome, 2).
 materialize(target, 2).
+materialize(metric, 2).
+materialize(threshold, 2).
+materialize(scope, 2).
+materialize(retailer, 2).
+materialize(expiresAt, 2).
 materialize(scannedProduct, 2).
 materialize(suggestedAlternative, 2).
 materialize(headline, 2).
 materialize(note, 2).
+materialize(reason, 2).
 materialize(value, 2).
 materialize(alg, 2).
 materialize(auditEntries, 2).
@@ -33,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"),
@@ -47,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),
@@ -91,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).
@@ -143,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").
 
@@ -194,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),
@@ -243,7 +256,11 @@ derivedFromNeed(insight, Need) :- derived_from_need(insight, Need).
 outcome(decision, Outcome) :- decision(decision, Outcome, _Target).
 target(decision, Target) :- decision(decision, _Outcome, Target).
 scannedProduct(scan, ProductName) :- scanned_product(scan, Product), product_name(Product, ProductName).
-suggestedAlternative(case, Alternative) :- suggested_alternative(case, Alternative).
+suggestedAlternative(case, Name) :- suggested_alternative(case, Alternative), product_name(Alternative, Name).
+threshold(insight, Threshold) :- threshold_display(insight, Threshold).
+scope(insight, "self-scanner @ pick_up_scanner") :- scope_device(insight, "self-scanner"), scope_event(insight, "pick_up_scanner").
+expiresAt(insight, Time) :- expires_at(insight, Time).
+reason(why, "The phone desensitizes a diabetes-related household condition into a scoped low-sugar need, wraps it in an expiring Insight + Policy envelope, signs it, and the scanner consumes that envelope for shopping assistance.") :- authorization_allowed(check).
 headline(banner, Headline) :- banner_headline(banner, Headline).
 note(banner, Note) :- banner_note(banner, Note).
 suggestedAlternative(banner, Name) :- banner_suggested_alternative(banner, Name).